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Introduction 


Programming with RT—11 examines the RT—11 facilities that 
enable you to develop executable programs in MACRO-11, 
FORTRAN IV, or BASIC—11. Programming with RT-11 
comprises two volumes. Volume 1 covers the program de- 
velopment process, RT—11 debugging aids, libraries, over- 
lays, and the FORTRAN IV and BASIC-11 subroutine con- 
ventions for MACRO-—11 interfacing. Volume 2 discusses the 
use of programmed requests to perform file and terminal 
input/output, foreground/background communication, and 
synchronous and nonsynchronous input/output opera- 
tions. 

Volume 2 contains chapters 8 through 20. Chapter 8, 
“Using System Services,’’ examines the system services: 
when to use them, how they work, and how to call them. 
Chapter 9, “Gaining Access to System Information,’ de- 
scribes the structure of the RMON fixed offset area and the 
function of each of its parts. Chapter 10, “Controlling Pro- 
gram Execution,” discusses chaining and passing com- 
mand lines to KMON on exit. Chapter 11, “Using In- 
put/Output Systems,” gives an overview of device I/O and 
describes the system components involved in an I/O trans- 
fer. Chapter 12, “‘Using Terminal Input/Output,” describes 
single-character J/O and commands to input or output text 
a line at a time. Chapter 13, “Using Multiterminal In- 
put/Output,”’ discusses the input and output of characters 
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for multiterminal support. Chapter 14, ‘““Using Queued In- 
put/Output,” examines synchronous queued I/O requests for 
writing to or reading from file-structured and non-file- 
structured devices. Chapter 15, ‘““Using Nonsynchronous 
Queued Input/Output,” discusses asynchronous queued I/O 
and event-driven I/O. Chapter 16, ‘Scheduling and Block- 
ing,’ examines’ event-driven blocking and _fore- 
ground/background scheduling. Chapter 17, ‘‘Transferring 
Data Between Jobs,” describes the sharing of buffers and the 
transfer of data between foreground and background jobs. 
Chapter 18, “Using Memory,” looks at the dynamic allo- 
cation of buffers and ways to manipulate the User Service 
Routine (USR). Chapter 19, “Using the Command String 
Interpreter,’’ examines the interface between the Command 
String Interpreter (CSI) and the user and programmer and 
describes related data structures and programmed requests. 
Chapter 20, ‘‘Writing Time-dependent Programs,” dis- 
cusses programs that make use of timed services, in partic- 
ular, mark-time requests, scheduling, and setting the sys- 
tem date and time. 


Equipment 


In order to do the practice exercises, you will need access 
to a working RT—11 system with at least 500 blocks of disk 
space for your files. By a working system, we mean that: 


e The RT-11 monitor program has been transferred 
from its storage disk to main memory (in other 
words, the system has been bootstrapped) 


e The FORTRAN IV compiler or BASIC—11 interpreter 
has been installed and is available for use 


Resources 


Although every effort has been made to make Program- 
ming with RT—11 self-contained volumes, you may need to 
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refer to the following manuals from the RT—11 documen- 
tation set for additional information: 


* RT-—11 Installation Guide ~ 

e RT-—11 Programmer’s Reference Manual 
e RT-—11 Software Support Manual 

¢ RT-11 System Generation Guide 

e RT—11 System Message Manual 

¢ RT-—11 System User’s Guide 

¢ RT-11 System Utilities Guide 


The documentation to which we refer throughout the text 
is written for RT—11 version 5.0. We also used a computer 
system equipped with RT—11 version 5.0 to generate the 
programs in our examples and practices. If you own a newer 
version of RT—11, you may also need a copy of the latest 
System Release Notes to determine the difference between 
your system and the one described here. 

Programming with RT—11 is written under the as- 
sumption that you know how to program in MACRO-—11, 
FORTRAN IV, or BASIC—11. The authors assume that you 
can manipulate files and get directory listings on an RT—11 
system and are familiar with RT—11 conventions for device 
and file specifications, the operation of the Foreground/ 
Background monitor, and monitor components and their 
functions. If you need additional information on RT—11 
conventions and programming procedures you may refer to 
the publications listed below: 


¢ Working with RT—11 (Digital Press, 1983) 


¢ Tailoring RT—11: System Management and Program- 
ming Facilities (Digital Press, 1984) 


e RT-11/RSTS/E FORTRAN IV User’s Guide 
e BASIC—11 Language Reference Manual 

e BASIC—11/RT—11 Installation Guide 

e BASIC—11/RT-—11 User’s Guide 
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For a directory of documentation products, write: 
Digital Equipment Corporation 

Circulation Department, MK01/W83 

Continental Boulevard 

Merrimack, NH 03054 


Notations 


The following symbols are used in this volume to repre- 
sent specific elements: 


(KEY) indicates keyboard and keypad keys, their func- 
tions, or key combinations 


COMMANDS _ (uppercase) indicates input 
Prompts (upper and lowercase) indicates computer output 


a) indicates parts of a;command that are optional 
(the brackets are not part of the command string) 


An example box acts as a window that shows either the in- 
teraction between the user and the computer or a portion 
of the codes in a program. If the code in an example does 
not include a label, blank spaces have not been included 
to account for the label field. 
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Using 
System Services 


In addition to the utility programs, RT—11 provides a large 
number of programmed requests and system subroutines 
(referred to as system services) which gain access to capa- 
bilities such as file creation, file maintenance, and event 
timing. 

If you are programming in FORTRAN IV, you reach 
the RT—11 system services through calls to the system sub- 
routine library SYSLIB.OBJ. This library has a package 
which handles character strings and supports routines for 
two-word integers. It also provides access to many system 
services obtained by MACRO-11 programmed requests. 
Using these services, you can write most applications pro- 
grams entirely in FORTRAN IV. 

In this chapter you will learn to call system service 
routines in FORTRAN IV, using SYSLIB functions or sub- 
routines and call programmed requests in MACRO-11 (us- 
ing the system macro library) and dynamically change the 
arguments for requests by using an argument block. You 
will also learn to write code to detect the success or the 
specific cause of failure of a given programmed request and 
trap error conditions that would otherwise cause the pro- 
gram to abort. 
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Programmed Requests 


You gain access to the RT—11 system services by using ma- 
cro calls or FORTRAN IV function or subroutine calls in 
your program. When your program is assembled or com- 
piled, and linked, these programmed requests provide ac- 
cess to the RT—11 monitor routines which perform func- 
tions such as I/O operations, system interrogation (for 
example, memory contents), and communication between 
multiple tasks. 

Figures 19 and 20 show the use of the PRINT pro- 
grammed request in a MACRO-11 and a FORTRAN IV 
program. The PRINT request prints characters from a spec- 
ified string at the console terminal. The two programs call 
on the same monitor routine to perform the print opera- 
tion. This routine performs the I/O operation more effi- 
ciently than the FORTRAN formatted I/O system. The ser- 
vices provided as programmed requests are listed and 
discussed in the RT—11 Programmer’s Reference Manual. 


Executing Programmed Requests 


When your program is executing, calls to system services 
cause a transfer of control to the appropriate monitor code. 

This code then processes the given arguments and per- 
forms the function requested. | 


Figure 19. 
MACRO-11 Program Using the .PRINT Request 


»- TITLE PRINEX 
;THIS MACRO PROGRAM PRINTS A STRING USING 
;THE PRINT REQUEST 
-MCALL .PRINT, .EXIT 
STRING: .ASCIZ /THIS IS A STRING OF CHARACTERS/ 
-EVEN 
ST: -PRINT #STRING 
~-EXIT 
~-END ST 
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Figure 20. 
FORTRAN IV Program Using the .PRINT Request 


PROGRAM PRINEX 


Cc THIS FORTRAN PROGRAM PRINTS A STRING 

C USING THE PRINT REQUEST 
CALL PRINT C’THIS IS A STRING OF CHARACTERS?’ ) 
CALL EXIT . 
END 


Load Image Code 


Most programmed requests generate code to move the re- 
quest arguments to some location in memory. In figures 19 
and 20 only one argument, the address of the string, must 
be copied into a general purpose register. When it has been 
copied, the request generates an emulator trap (EMT) in- 
struction whose execution causes control to be passed to 
an address listed in a monitor address (or dispatch) table. 

The expansion of a programmed request may have as 
few as one or two machine instructions. The number of in- 
structions depends on the operations performed by that 
programmed request or the number of arguments specified 
in a macro call. 


The EMT Instruction 


When the EMT instruction is executed, control is passed to 
the EMT processor routine in the monitor. The EMT in- 
struction execution uses a sequence of events very similar 
to an interrupt which transfers control to an interrupt ser- 
vice routine. This event sequence follows: 


1. The current PC (program counter) and PSW (proces- 
sor status word) registers are saved on the stack. 


2. The PC and PSW registers are loaded with the con- 
tents of the EMT vector, locations 30 and 32. Loca- 
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tion 30 contains the address of the EMT processor 
routine in the RT—11 monitor; location 32 contains 
the processor status the monitor uses to execute the 
request. 


3. The monitor processes the EMT. The type of request 
is determined and argument checking is done. In- 
valid or incorrect arguments cause control to be re- 
turned immediately to the requesting program. 


4. The request is processed; for example, a string of 
characters is printed on the console. 


5. The monitor executes an RTI (return from interrupt) 
instruction, which restores the PC and PSW register 
values saved on the stack, and control returns to the 
requesting program. 


The low-order byte of the EMT instruction contains an 
EMT code, which is interpreted by the monitor according 
to its value. Table 1-1 in the RT—11 Programmer’s Refer- 
ence Manual lists these codes and their meanings. The im- 
portant EMT codes are 375, 374, and 340 to 357. The forms 
of programmed requests that generate each of these EMT 
codes are discussed later in this chapter. Figure 21 shows 


Figure 21. 
Executing an EMT Instruction 


MAIN MONITOR 


PROGRAM EMT VECTOR CODE 


30/32 


VALIDATE ARGUMENTS 
PROCESS EMT INSTRUCTION 


CHECK FOR ERROR 
CONDITIONS 


CHECK FOR FATAL ERRORS 
(FATAL ERRORS ABORT 
YOUR PROGRAM) 


RETURN TO USER 
PROGRAM WITH 
ERROR INDICATOR 
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the flow of control during the execution of an EMT instruc- 
tion generated by a programmed request. 


Types of Services 


Several types of system services can be accessed by pro- 
grammed requests and FORTRAN IV subroutines in SYS- 
LIB. The types of services are described in table 7. 


MACRO—11 Specific Implementation 


MACRO-—11 programmed requests are implemented as sys- 
tem macros. The macros are collected in the system macro 
library SYSMAC.SML and are automatically called when 
needed during program assembly. 

All programmed requests start with a period (.) to dis- 
tinguish them from ‘programmer-defined symbols and 
macros. Most programmed requests need arguments, which 
must be valid assembler expressions. All programmed re- 
quests must be explicitly declared using the .MCALL di- 
rective to make the macro definition available from the sys- 
tem macro library. 

This section focuses on services which have macro 
calls. Additional capabilities are available using routines 
found in the FORTRAN IV system subroutine library SYS- 
LIB.OBJ discussed later in this chapter. MACRO—11 pro- 
grams can gain access to some of these subroutines using 
the standard MACRO-11 calling conventions. 


Form of the Macro Call 


You specify MACRO-—11 programmed requests in two ways. 
With requests such as .PRINT or .GTLIN, you simply sup- 
ply the name of the request followed by the arguments. The 
format is: 


Table 7. 
System Services 


Type 


Program initialization 
and control 


System or job resource 
and status interrogation 
Command translation 


File operations 


File I/O operations 


Console terminal I/O 


Multiterminal I/O 
Foreground/background 
communications 


Timer support 


_ System job communication 
Interrupt service routines 


Extended memory functions 


INTEGER*4 


FORTRAN IV character 
string functions 


RADIX-50 conversion 


Miscellaneous FORTRAN IV 
routines 


Functions 


Allocates memory 

Allocates input/output resources 
Turns devices on and off 
Processes errors 

Supplies date and job information 


Includes the Command String 
Interpreter (CSI) 


Open, close, create, rename, delete, 
and change protection status or 
creation date of files 


Perform synchronous and 
nonsynchronous |/O 


Controls I/O operations and sends 
and receives data on the console 
terminal 


Allows your program to control and 
perform I/O on 1 to 16 terminals 


Enable two-way transfer of data in 
memory buffers 


Starts or ends jobs on the basis of 
elapsed system-clock time 


Allows jobs to communicate 


Allow interrupt service routines to 
communicate with the monitor by 
means of macros available in the 
SYSMAC library 


Include four types of requests for 
creating and using extended memory 
(extended memory requests are not 
available for FORTRAN programs) 


Performs arithmetic operations on 
this data type (for FORTRAN 
programs) 


Compare, copy, find character strings 
and concatenate ASCII strings 


Converts FORTRAN IV to RADIX-50 
format and RADIX-50 to FORTRAN IV 


Allow you to examine and modify 
absolute memory locations and 

specify a FORTRAN IV subroutine as an 
interrupt service that run at a specific 
priority 
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-PRGREQ _arg1,arg2,...,argn 


Here ‘‘“.PRGREQ” is the name of a programmed request and 
“arg1,arg2,....argn”’ is the list of arguments you give. 


IMEC Ee PE NICH LO EEN itm ARN EAM CNN NN TNE EAM MEL EO SHIN EEE EC HDR ETERNITY MENA AEA SS ABI A" KRIS Abe PR 


_EXAMPLE 


-PRINT #STRING 


— 


es ab kn it a Nm i i abd a touintiue nei anania ua tnnedanneit anima ihcAS Mii Sities cn tdi Mini indie aihendt naa RaOMKha di 


With requests such as .PEEK or .POKE, you supply the 
name of the request, the symbolic address of a memory area 
where the arguments will be stored, and the arguments. The 

format is: 
. -PRGREQ area, arg1,arg2,...,argn 
Here ‘‘..PRGREQ”’ is the name of a programmed request; 
“area” is the symbolic label pointing to the EMT argument 
block, which is a set of words used to pass the arguments 


to the monitor; and ‘‘arg1,arg2,...,argn” is the list of argu- 
ments you give. : 


EXAMPLE seus ee Reis 
.GTIM  — #AREA, #TIMBUF 


AREA:  .BLKW 2. Argument Block for GTIM 
- TIMBUF: .BLKW 2 ;Buffer to receive System Time 


” ort enemys cement ay 
H 
et 
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Passing of Arguments 


Macros of the simple format (type 1) generate either an EMT 
374 or one of the EMTs in the range 340 to 357. Requests 
that generate an EMT 374 have only one argument. RO con- 
tains a function code in the high-order byte, to indicate 
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Macro Expansion 


Error Return 
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which request is used. Requests that generate EMTs 340 to 
357 are each unique to one programmed request. The cor- 


~ responding programmed requests have their arguments either 


in RO, or on the stack, or both. 

The macros in which you specify a memory area (type 
2) always generate an EMT 375. RO contains the address of 
“area” within your program. The first word of the ‘‘area’’ 
block is set by the programmed request to identify the call. 
The remaining words in the block may contain point to 
each of the arguments ‘“‘arg1”’ to ‘‘argn.”’ 

The macro expansion moves the specified aictimonts 
into the argument block. If your program has previously 
moved values into the argument block, you can omit those 
arguments in the macro call. In this way you can change 
the macro arguments dynamically. 

RO is often used to return important information to your 
program after the request has completed, and so it is never 
preserved across a call. 


You seldom need to examine the actual code generated on 
expansion of a programmed request; however, you may find 
it useful, or even necessary, to trace through the expansion 
in order to detect programming errors. An example of a 
MACRO-11 programmed request expansion (shown in fig- 
ure 22) is the assembly listing of the code in figure 19. The 
.LIST MEB directive is used to direct the assembler to list 
the expansion. Note that the expansion of .PRINT passes 
the address of the string to the EMT processor via %0, which 
is the register RO. 


In addition to processing programmed requests used in your 
program, the monitor can return error information based on 
the results of executing these requests. If an error occurs 
during execution of the request, the monitor returns to your 
program with the C-bit set. 
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Figure 22. 
Expanding the .PRINT Programmed Request 


1 -TITLE PRINEX 

2 -LIST MEB 

3 ;THIS PROGRAM PRINTS 

4 3A STRING USING THE 

5 ;PRINT REQUEST 

6 -MCALL .PRINT, .EXIT 

7 000000 101 040 123 STRING: .ASCIZ /A STRING/ 
000003 124 122 111 
000006 116 107 000 

8 -EVEN 

9 000012 ST: -PRINT #STRING 
000012 012700 000000’ MOV #STRING,2%0 
000016 104351 EMT “0351 

10 000020 EXIT 
000020 104350 EMT “0350 

11 000012’ ~END ST 


Some programmed requests may return one of many 
possible error conditions. Each condition is identified by a 
code returned by the monitor in byte 52. Your program 
should refer to byte 52 with absolute addressing, gaining 
access to it as a byte. Never refer to location 52 as a word 
because byte 53 has a separate function. Chapter 9, ‘“‘Gain- 
ing Access to System Information,” gives more details about 
this byte and other system data. The code in figure 23 tests 
the result of a programmed request execution. 


Figure 23. 
Error Checking Code 


AREA: .BLKW M ; Argument block 
ERRBYT=S2 ; Error byte Cabsolute address) 


-READ AREA, ...... 
BCS ERROR 3; Check if programmed request 
5; was executed without error 


ERROR: TSTB #ERRBYT 3 Now check type of error 
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The codes that may be returned for any programmed 
request are individually listed and defined in chapter 2 of 
the RT—11 Programmer’s Reference Manual. You will find 
that many requests return no error information. 


Serious Error Conditions 


Serious errors cause a message to be generated by the mon- 
itor and printed on the console terminal. Fatal errors cause 
termination of your program, instead of an error return. The 
monitor prints a message indicating the type of error after 
the code: 


?MON-F - 


Some fatal errors can be trapped and have their values 
returned in byte 52. These are discussed below. You should 
always supply appropriate error checking after a program 
request. 


_ Return of Auxiliary Information 


In general, the content of RO is not saved across a pro- 
grammed request. It may be used to return important infor- 
mation to your program. All other registers are preserved. 
For example, the programmed request .LOOKUP opens a file 
on a device. On completion, RO contains the number of 
blocks in the file that has been opened. 

Chapter 2 of the RT—11 Programmer’s Reference Man- 
ual describes each of the MACRO-11 programmed re- 
quests. Each description indicates what the request does, 
how it is called, what information is returned in RO, and 

_ what possible error conditions may be returned. 


FORTRAN IV Specific Implementation 


The FORTRAN IV implementation of programmed re- 
quests is in the form of system subroutines, which are stored 
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in the system library SYSLIB.OBJ. These subroutines im- 
plement a number of the programmed requests, as well as 
other functions listed in table 7. 


Form of the FORTRAN Call 


SYSLIB subroutines are called in the same way as user- 
written subroutines. SYSLIB contains both function and 
subroutine subprograms. Function subprograms receive 
control by means of a function reference, in the form: 


Variable = function-name (arguments) 


Subroutine subprograms are called using the CALL state- 
ment: 


CALL subroutine-name (arguments) 


All routines in SYSLIB can be called as function sub- 
programs to return the value of the routine, or as subrou- 
tine subprograms if no return value is needed. If you use a 
function call for a SYSLIB subprogram that does not return 
results, the value returned has no meaning. 

Figure 24 uses the AJFLT function subprogram, which 
converts an INTEGER*4 value to a REAL*4 value, return- 
ing it as the function value. The code in figure 24 converts 
the INTEGER*4 value in JVAL to REAL*4, multiplies it by 
3.5, and stores the result in VALUE. 


Figure 24. 
A SYSLIB Call 


C DECLARE VARIABLES 
REAL*4 VALUE 
INTEGER*4 JVAL 

C PROGRAM -CODE 


VALUE=AJFLTCJVAL)*3.5 
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Some SYSLIB routines that return a condition code value 
allow you to determine if the operation of the routine was 
successful. Your program must check this value to see if an 
error occurred. For example, the function JADD computes 
the sum of two INTEGER*4 values. The result assigned to 
the variable on the left side of the assignment operator (=) 
is set to one of the four values, depending on the result of 
the computation. So, the code: 


K = JADD(I,L,M) 


computes the sum of I and L, stores the result in M, and 
returns a condition code in K. The possible codes for the 
JADD function are: 


—2 For an overflow 
0 =«‘ For a normal return of zero 
1 Fora normal return with a positive result 


=1 For a normal return with a negative result 


The use of JADD to check for an error on return from 
a SYSLIB call is shown below. 


cep ycygrre oneness ene gamers nre enone wees 
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You should always check for an error return after any SYS- 
LIB call. 


Other Error Conditions 


Other system services that allow your program to control 
the monitor’s action when serious error conditions occur 
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are mentioned here primarily to let you know that they ex- 
ist. The RT—11 Programmer’s Reference Manual provides 
details and examples of use. 


Control of Serious Error Conditions 


Trap Handlers 


Normally, when a serious error occurs in a programmed re- 
quest, the system aborts the job and displays an error mes- 
sage. In some applications you may want a program to re- 
cover, or continue, after a serious error. If the .SERR request 
is used, then any serious errors are reported to the pro- 
gram. The carry bit is set, and byte 52 contains a negative 
code to indicate that the error is serious. Table 2—2 of the 
RT—11 Programmer’s Reference Manual lists the error codes 
returned by .SERR. 

The .HERR request (the system default) allows the sys- 
tem to abort your program on serious errors and generate a 
system error message. This request overrides the .SERR 
request. 


Some programs execute instructions or reference memory 
that may not be present. These programs may check whether 
particular instructions (for example, floating point instruc- 
tions) are supported by the CPU, whether particular hard- 
ware devices (such as the RT—11 memory management unit, 
I/O peripherals) are present, or the amount of memory 
available. If a tested address does not exist, a trap to 4 oc-- 
curs. If an instruction that is checked for is not supported, 
a trap to 10 occurs. RT—11 normally aborts the program 
when a trap to 4 or 10 occurs. Before aborting the program, 
the monitor displays a message: 


2?MON-F-TRAP to 4 
or 
?MON-F-TRAP to 10 
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To prevent the monitor from aborting the program, you can 
use the .TRPSET programmed request. 

You write a trap handler to recover from the error. The 
.TRPSET request declares the address of the trap handler. 
The trap handler routine must also issue another .TRPSET 
request before it exits because RT—11 cancels .TRPSET each 
time a trap occurs. See chapter 2 of the Programmer’s Ref- 
erence Manual for details. 


Floating Point Exception Handlers 


If you have the floating point hardware option, the .SFPA 
request allows you to set up a routine to handle floating 
point exceptions. If you do not set up a trap address, then 
your job is aborted by the monitor when a floating point 
exception condition occurs. .SFPA is also used under the 
FB and XM monitors to allow the floating point registers to 
be used by more than one job. 
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Gaining 
Access to 
System 
Information 


The RT—11 monitor maintains in memory a large amount 
of information about its current state and the state of jobs 
currently running. Some of this information is useful to 
applications programs and can be obtained from MACRO-— 
11 and FORTRAN IV programs using system services pro- 
vided for that purpose. In this chapter you will learn how 
to read and modify this data using the programmed re- 
quests: .PEEK, .POKE, .GVAL, and .GTJB (MACRO-—11) and 
IPEEK/B, IPOKE/B, ISPY, and GTJB (FORTRAN IV). 

You will also learn to use two MACRO-11 pro- 
grammed requests, .MFPS and .MTPS, to gain access to the 
processor status word (PSW) independent of the processor 
type. 

When you have completed this chapter, you will be 
able to obtain data from any location in the system com- 
munication area; get the data from any location in the 
RMON fixed offset area or in the job’s impure area; get job 
information from RMON using the GTJB request; and iden- 
tify the restrictions on the use of the RMON fixed offset area 
and the impure area. 
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System Information 


The Resident Monitor (RMON) maintains a large amount of 
information about its own status and that of jobs currently 
running. This is held in three main areas of memory: 


¢ The system communication area (SYSCOM) 
¢ The RMON fixed offset area 


e The impure area (for each job) 


Figure 25 shows the location of these areas in the 
memory of a typical FB monitor system. 

The system communication area (SYSCOM) occupies 
absolute locations 40 to 57 in memory. This area contains 
information about the job currently running. Some of this 
information is provided by the linker and copied into 
memory when the program is loaded. The remaining loca- 
tions are used at run time to enable RMON and the job to 
communicate. 

The structure of RMON differs from monitor to moni- 
tor, depending on the SYSGEN options selected. Some data, 
however, are always located at a fixed position relative to 
the start of RMON. This area, called the RMON fixed offset 
area, contains information about the monitor itself and about 
the current hardware and software configuration. 

Each job also has its own impure area, which contains 
information specific to the job, including the terminal in- 
put/output buffers. This area is maintained and used by 
RMON, but user programs can also retrieve data from it 
(except in SJ systems). 


System Communication Area 


The system communication area (SYSCOM) occupies lo- 
cations 40 (octal) to 57 (octal) in memory, and contains in- 
formation about the job currently executing. The contents 


of each of these locations are described below. 


157,776 


500 

476 
BYTES 6 
(OCTAL) 57 


0 INTERRUPT VECTORS 
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Figure 25. 
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Information Areas in a Foreground/Background System 


I/O PAGE 


MEMORY 


SYSTEM DEVICE HANDLER 


_ BACKGROUND IMPURE AREA — 


_ RMON FIXED OFFSET AREA — 


FOREGROUND JOB SPACE 


BACKGROUND JOB SPACE 


DEFAULT BACKGROUND STACK 


"SYSTEM COMMUNICATION 


TRAP VECTORS 


RESIDENT MONITOR 
(RMON) 
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Information set by the linker and copied into memory 
from the load image: 


1. Word 40 (locations 40 to 41) contains the normal 
start address of the first executable instruction in the 
program. This is used by the R, RUN, and START 
commands. 


2. Word 42 (locations 42 to 43) contains the initial 
value of the stack pointer for the job currently exe- 
cuting. By default, the top of the stack is immediately 
below the lowest program address (at location 776 for 
a background job). The default can be changed using 
the .ASECT directive or, for a background job, the 
linker /STACK option. 


3. Word 50 (locations 50 to 51) contains the program 
high limit—the highest address your program can 
use. In XM systems, it is the address of the top of the 
root section plus the low memory overlay regions. 
Programs must never change this word directly. If 
you want to change it, use the .SSETTOP directive. 


Information given by RMON to the job: 


1. Byte 52 is the monitor error byte. If RMON detects 
errors in a programmed request, it places the error 
code in this byte and sets the carry bit. 


2. Word 54 (locations 54 to 55) is the address of the 
start of RMON. This can be used as a pointer to the 
RMON fixed offset area, as discussed later. Your pro- 
grams must never modify the contents of this word. 


Information given by the job to RMON: 


1. Word 44 (locations 44 to 45) contains the job status 
word (JSW) used to control the operation of some of 
the programmed requests and to enable certain pro- 
grammed request features. This word is discussed 
later. 
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2. Word 46 (locations 46 to 47) contains the alternate 
User Service Routine (USR) load address. Its value is 
normally zero, which indicates that the USR swaps 
into its default location below RMON, the foreground 
and system jobs, and the device handlers. If you set 
this word to a value other than zero, either in the 
load image file or at run time, this value is used as 
the address at which the USR swaps. The swapping 
position should be selected with care. For more in- 
formation, see chapter 18, ‘‘Using Memory.” 


3. Byte 53 is the user error byte. The user job sets a 
value in this byte to indicate whether any errors have 
occurred during program execution. For example, 
code 0 means that the job has terminated success- 
fully. In indirect file processing, KMON examines 
this byte upon program termination. If a significant 
error has been reported, KMON can abort any indi- 
rect files in use when commands that follow depend 
on successful completion of this program. 


4. Byte 56 (the fill character) and byte 57 (the fill count) 
are used to specify the type and number of fill char- 

. acters needed by some types of low-speed terminals. 
Because of the transmission rate, these terminals 
must have fill characters (nulls) inserted after certain 
characters. More information is given in chapter 2 of 
the RT—11 Installation Guide. 


The contents of locations in the system communica- 
tion area are shown in figure 26. Detailed information is 
given in chapter 2 of the RT~11 Software Support Manual. 


The Job Status Word (JSW) 


The settings of the individual bits of the JSW (word 44 in 
the system communication area) are used to control the op- 
eration of certain programmed. requests and indicate whether 
certain special features are enabled. Some of the bits may 
be modified by user programs either at load time or during 
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Figure 26. 
System Communication Area (SYSCOM) 


aes 


MEMORY 


cs FILL COUNT 
| so | FILL CHARACTER 


RMON BASE ADDRESS 


USER ERROR CODE 
MONITOR ERROR CODE 


HIGH MEMORY LIMIT 


USR LOAD ADDRESS 
(NORMALLY 0) 


JOB STATUS WORD 
(JSW) 


INITIAL VALUE OF 
STACK POINTER 


57 


BYTES 40 PROGRAM 
0) 


program execution. The word may also be set from the ter- 
minal or from an indirect file using the D (deposit) com- 
mand. 


Application Examples 


Later you will need to access locations in the system com- 
munication area for specific applications, for instance: 
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1. You may want to write programs that do not echo in- 
put received from the terminal, for example, pass- 
words. You can do this by setting bit 12 of the JSW 
(the special mode terminal bit). 


2. When you use programmed requests to perform 
queued I/O, you may have to load a device handler 
from your program into memory. It is convenient to 
place the handler immediately above your program. 
To do this, you need to know your program’s high 
memory limit, which is held in word 50 of SYSCOM. 


Gaining Access to SYSCOM and Other 
Absolute Locations 


RT-—11 provides certain programmed requests that enable 
you to call absolute locations from MACRO-11 and FOR- 
TRAN IV programs. These requests are .PEEK and .POKE 
for MACRO-11, and IPEEK/B and IPOKE/B for FORTRAN 
IV. | 


Reaching Absolute Locations 
from MACRO—11 Programs 


The .PEEK programmed request returns in RO the contents 
of a memory location. .POKE changes the contents of a lo- 
cation. The macro calls are: 


PEEK area,addr 
.POKE _ area,addr,value 


In these macro calls: 


area is the address of a two- or three-word EMT 
argument block 
addr is the address of the location tc examine 


value is the new contents to place in the location 
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The following example shows how to load RO with the base 
address of RMON from word 54 of SYSCOM. 


I CORO ORS NARA TRIAS IL EM 


“EXAMPLE 


NE TONLE ET ELT ILE LILO ENCE LL ACL LLL LC EOL ELL LEI 


PEEK #EMTBLK, #54 RMON dddvess” to RO Soar | 


i ae ert diet ei Lu Sa seh ES Is Sl ng ese Smet ao dea 


When you use .POKE, be sure that your addressing 
modes are correct. In the following example, the two state- 
ments are equivalent: because R2 contains the address of the 
location you want to change (such as 44), and R1 points to 
the data you want to move. 


sh ot aie Ra EN SZ RA MC RSAC NAAN MALORNE AUC CODA BERGE BP ALLL SRC RTET Se SERS SLED oe 


EXAMPLE 


“POKE #OREA, R2, CRI) ‘Move! ‘data mornted’ to by RT 
a -3to address in R2. ae 
mov pO CRae  3Move data pointed to by RI ee “| 

Sa rcs ee es location pointed 
ito by R2 aS 


Unless you intend to use the XM monitor, you can also 
access absolute addresses directly. In the following exam- 
ple the instruction sets bit 6 of word 44 (the JSW). 


re RAT PI GSES ace UAICN TAA GHEE EAH pAb LOR RNAI TE SENTIGE Seu RUN ARCEMIS GS LPS RUFTE RTPI NULE UR @ ERE TE TRL EEO a 


“EXAMPLE 


“#00, ened fe fet ce eed 


Always use the .PEEK and .POKE programmed re- 
quests to access absolute memory locations that are in low 
memory, so that your programs can be run under any mon- 
itor. 

Notice that .PEEK and .POKE only access word loca- 
tions. If you want to access a byte, use .PEEK to retrieve 
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the complete word and change only the bits in the high- or 
low-order byte, as appropriate. You can also use this method 
to set or clear specific bits in a word or byte, by combining 
.PEEK; a BIS or BISB instruction to set bits, or a BIC or BICB 
instruction to clear bits; and .POKE. 

When you use .PEEK followed by .POKE, you must 
move the value returned in RO to another location before 
you perform any operation on that value. Since these two 
requests use an EMT argument block, RO is corrupted when 
you issue .POKE. The following example shows the correct 
use of .PEEK and .POKE to clear bits 5 and 6 of the JSW. 


POE ween aN EN OMEN RNR REANIM RUINS EMER MAES AIO RAAT AN CE CEE AA NCI RE ERHARD NCEE A RM ty EMRE i IRS 


| EXAMPLE 
i mov RO,R1 ;Move value to Rl 
BIC. #140,R1 sClear bits 5 and 6, then 


i - PEEK #EMTBLK , #44 ;Get JSW in RO 
} 

i -.POKE  #EMTBLK,#44,R1  ;Write JSW back from R1 i 
| | 


Wns stemeboai h tinea tN AA Ato SN ANCL tian COS AS im te A en AO SO NE me: Aa ni 8 oh ins 


You should use .PEEK and .POKE with all RT-11 
monitors for compatibility. 


Reaching Absolute Locations 
from FORTRAN IV Programs 


The FORTRAN IV language standard does not provide 
statements that allow your program to access memory lo- 
cations by their absolute address. You must use the IPEEK 
and IPOKE functions to examine and modify these 
locations. 

The IPEEK function returns the contents of the ad- 
dress specified as an argument. By default, the address is 
interpreted as a decimal value, so if you want to reference 
an address in octal, you must precede the first digit with a 
quotation mark (‘‘). For instance, in the following example, 
the statement loads the variable IRMON with the contents 
of word. 54 (octal) of SYSCOM—the base address of RMON. 
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EXAMPLE 


iS io ono Seth ions an ccc as RDO NS Seer exerts iN ska owe Cl 


Notice that the address given must be an even number 
because it is a word address. The corresponding function 
to retrieve the contents of a byte address is IPEEKB. The 
following example shows a statement that stores the user 
error code from byte 53 (octal) in the variable IUSERR. 


S ‘EXAMPLE see eben ee re: S 
Ee 


ss IUSERR= IPEEKBC"S3)_ oe pee al 


iit cal ioe la aca Nt oa te a as nase acnandeans ciel AE eGR oes oo 


The subroutines IPOKE and IPOKEB load a specified 
value into a specified word (IPOKE) or byte (IPOKEB) ad- 
dress. The statement in the following example loads the 
contents of variable IUSR into word 46 (octal)—the alter- 
nate USR swap address. 


It actut hat Godse teeieanee tian memeetien maeetaeeenee retirees eemaeenaaise eagtaeanceaeattemateeman castes emeaamacautenetaet: maciete tela mamta ante eae cm tcateatanmemsmnae 


EXAMPLE 


“CALL TPOKEC*46, 1USR)_ 


forrrrr. 
ES Seen 
i Sata EY Se a 


Ft ne re eee Ce ee ee es ee nee Pent ee 


For words such as the JSW, you will usually want to 
set or clear specific bits in the word instead of modifying 
the complete word. You can do this by combining IPEEK, 
a logical operation (such as a logical OR), and IPOKE. The 
logical operation uses a bit pattern called a mask. You can 
use this combination to set all the bits of a mask in the word, 
or clear all the bits of a mask from the word. 

In the following example, a mask of 5 (binary 101 where 
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bit O and bit 2 are set) is used to set and then clear bits 0 
and 2 in a word that has value 3 (binary 011). 


é 
ewer 


EXAMPLE 


To set bits 0 and 2: 


| word 011 
mask 101 
| resultof.OR. 111 


To clear bits O-and’2: 


word 011 
.NOT. mask 010: 


result of .AND. 010 
i 


5 
‘Bisa tii. $e: Dst aS: soc MMi A NNSA ARS UNS hn EHH MEE DANSE RSE ASA EEE COSA EREDAR AREAL AAA SLOANE ABE AIA LEA AEE AA NESS 


Figures 27 and 28 show FORTRAN IV subroutines that 
set and clear specific bits of a word. 

The following code offers a shorter and more efficient 
way to perform the same operation. To set a bit you can 
use the statement: 


CALL IPOKE(IADDR,IPEEK(ITADDR).OR.IMASK) 


Figure 27. 
FORTRAN IV Bit-setting Routine 


CALL BITSETC"44,"1400) ‘SET BITS 8 AND 3 OF THE JSW 


SUBROUTINE BITSETCIADDR, IMASK) 


C... SETS ALL BITS IN "IADDR" WHICH ARE SET IN 
CC... “IMASK". THE OTHER BITS ARE NOT CHANGED. 
IOLD=IPEEKCIADDR) 


INEW=IOLD.OR.IMASK 
CALL IPOKECIADDR, INEWD) 
RETURN 

END 
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Figure 28. 
FORTRAN IV Bit-clearing Routine 


CALL BITCLRC"44,"1400) 'CLEAR BITS 8 AND 9 OF THE JSW 


SUBROUTINE BITCLRCIADDR, IMASK) 


C... CLEARS ALL THE BITS IN “"IADDR" WHICH ARE SET 
C... IN "IMASK™". THE OTHER BITS ARE NOT CHANGED. 
IOLD=IPEEKCIADDR) 


INEW=IOLD.AND. .NOT.IMASK 
CALL IPQKECIADDR, INEW) 
RETURN 

END 


To clear a bit: 


CALL IPOKE(IADDR,IPEEK(IADDR).AND..NOT.IMASK) 


hrm tenn ma pete mre HEMI mH SR ARPA EET MR CE PATI PEO SR HO EER PR 


EXAMPLE 


4 


CALL TPOKEC"44, IPEEKC"44). OR. "1002, 
sets bit 6 of the JSW. 


Beckisiisldes ieee a toieeainadints Senet na oa ee ene | 


: 
e 
| 
[ 
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RMON Fixed Offset Area 


The location of routines and data within the resident mon- 
itor depends on the SYSGEN options selected, so it differs 
from monitor to monitor. Some data, however, is always 
located at the same position relative to the start of RMON. 
This area is called the RMON fixed offset area. It contains 
information about the monitor itself, the current hardware 
configuration, and certain software conditions. 


Contents of the RMON Fixed Offset Area 


The full list of the contents of the RMON fixed offset area 
is given in table 3—8, chapter 3 of the RT—11 Software Sup- 
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port Manual. Some of the more commonly called offsets in 
this area are: 


¢ Word 266 contains the default USR base address. 
This is the address where the USR resides when it is 
called into memory by the background job, and loca- 
tion 46 of SYSCOM is zero. 


¢ Byte 276 is the monitor version number. 
¢ Byte 277 is the monitor release number. 


¢ Word 300 is the configuration word. The bit settings 
within this word give information about the hard- 
ware configuration and software conditions on your 
system. 


¢ Word 370 is the extension configuration word. (See 
word 300.) 


e Word 372 is the system generation features word. 
This location holds information indicating which ma- 
jor SYSGEN options are present. 


Application Example 


Bit 5 of the configuration word indicates whether your sys- 
tem has a 60- or 50-cycle clock. You might want to write a 
program that correctly processes the time and date infor- 
mation available through programmed requests (.GTIM and 
-DATE) under a 50—Hz or 60—Hz system. Such a program 
needs to refer to the RMON fixed offset area to find out at 
which frequency the system is running. Time-dependent 
programming is covered in chapter 20 of this book. 


Retrieving Data from the RMON 
Fixed Offset Area 


RT-11 has programmed requests specifically designed to 
retrieve data from the RMON fixed offset area. In MACRO-— 
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11 programs, the .GVAL programmed request performs this 
function. The statement in the following example returns 
the contents of offset 266 (the normal USR swapping ad- 
dress) in RO. EMTBLK must be a two-word EMT argument 
block. 


[= RTO RL REN DRE PRL HL AHEM SEC ERLE Ute SEY I RR NPG PU MORRIS AML RE RMR IRS Ee eR mane smo oteone eh nenaeauneen 


eee | 


| EXAMPLE rs 
 .GVAL = #EMTBLK, #266 


lin Sur AABN eg dna ee. Cee NITEM hate i A na tat na NN a oan eB SE 


When writing user programs, beware of modifying the 
contents of the RMON fixed offset area. This causes changes 
within the monitor. If you want to change the contents of 
the monitor, you use .PVAL (MACRO-11) or IPUT (FOR- 
TRAN IV). The RT—11 Programmer’s Reference Manual 
covers this topic in detail. 

In FORTRAN IV programs, you use the ISPY system 
service function to retrieve data from the RMON fixed off- 
set area. ISPY calls the .GVAL programmed request to re- 
turn the integer value of the word at a specified offset from 
the base address of RMON. The following example returns 
the configuration word (offset 300) in the variable ICONF. 


Sa cna eee ace 
e | EXAMPLE ee 
ICONF =1SPYC"300). ee es ee ee 


lis iS RR ti Re SS Wi NSBR i ach GR NN RO ii aD NON tah ae dead boa kane a tbdaaiNt habe 
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Impure Area 


Each job under the FB and XM monitors has its own im- 
pure area which is maintained by the resident monitor. This 
area contains job-dependent data used primarily for: 


¢ Input/Output 
e Scheduling and blocking 


e Memory access control (XM only) 
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The impure area for the background job is located 
within RMON, above the fixed offset area. The foreground 
job impure area is located below the foreground job and its 
stack (refer to figure 25). 

The contents of the impure areas are listed in table 3— 
13 in chapter 3 of the RT—11 Software Support Manual. 
Notice that some locations cannot be addressed as fixed 
offsets, since locations change from one release of RT—11 
to the next. SYSGEN options also affect these locations. 


Retrieving Data from the Impure Area 


To gain access to locations from the start of the impure area 
at fixed offsets, you need to know: 


¢ The address of the start of the impure area 
e The fixed offset 


You can use the GTJB (get job information) pro- 
grammed request to get information about the job, includ- 
ing a pointer to the impure area. The syntax of the request 
for MACRO-11 is: 


.GTJB area, addr 


In this request, ‘‘area’’ is the address of a three-word EMT 
argument block, and ‘‘addr” is the address of an eight- or 
twelve-word block in which system information related to 
the job is returned. 

The syntax of the GTJB request for FORTRAN IV is: 


CALL GTJB(array) 


In this request, ‘‘array” is an eight- or twelve-word integer 
array in which the data is returned. | 

Under FB or XM monitors that have the system jobs 
feature, twelve words of storage must be allocated in your 
program for the job information to be returned. Otherwise, 
eight words are sufficient. On return from the request, word 
5 of this area contains the address of the job’s impure area. 
This word has no meaning under the SJ monitor. 
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Figure 29. 
MACRO-11 Code to Retrieve Data from Offset 32 


AREA: .BLKW 3 sEMT ARGUMENT BLOCK 
BLOCK: .BLKW 8. ;JOB INFORMATION AREA 


-GTJB #AREA,#BLOCK ;GET JOB INFORMATION 


MOV . BLOCK+10,R1 ;ADDRESS OF IMPURE AREA 

;FROM WORD S CBYTE 10 OCTAL) 
ADD #32,R1 ;ADD OFFSET (€32) 
-PEEK #AREA,R1 ;RETRIEVE GUTSTANDING I/O 


;COUNT FROM IMPURE AREA INTO RO 


Figure 30. 
FORTRAN IV Codes to Retrieve Data from Offset 32 


INTEGER*2 IBLOCKC8) 
Ces JOB INFORMATION AREA 

CALL GTJBCIBLOCK) 

IWORD=IPEEKC"32+IBLOCKCS)) 
C... ADD OFFSET TO START ADDRESS OF IMPURE AREA 
C... AND RETRIEVE THE OUTSTANDING I/0 COUNT. 


When you know the address of the start of the impure 
area, add the offset of the location you want to access. Then 
access the contents of. the location in the area using the 
-PEEK (for MACRO-11) or IPEEK (for FORTRAN IV) pro- 
grammed requests. For instance, suppose you want to know 
how many I/O requests are outstanding for your job. This 
is held in offset 32 (octal) of the impure area. Figures 29 
and 30 show MACRO-—11 and FORTRAN IV code that re- 
trieve data from this location. 


‘ 


Gaining Access to the Processor Status 
Word 


Two programmed requests, which can only be used in 
MACRO-11 programs, allow processor-independent ac- 
cess to the processor status word (PSW). The two requests 
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are .MFPS and .MTPS. The contents of RO are not de- 
stroyed by either call. The .MFPS request is used to exam- 
ine the priority bits only. Condition codes are destroyed 
during the call. The .MTPS request is used to load the 
priority bits. 

These requests are useful since they make programs 
transportable. Some PDP—11 models support direct access 
to the PSW via address 177776, while others only support 
the MTPS and MFPS instructions. Some angers support 
both methods. 
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Controlling 
Program 
Execution 


This chapter discusses the different ways you can start and 
stop program execution. Normally, you use the RUN com- 
mand to load a background program into memory and start 
execution at the first instruction. Sometimes, such as when 
you are debugging, you may want to separate the tasks of — 
loading the job and starting execution, or start execution 
at a different address. This chapter describes the monitor 
commands used to do this. It also describes how to write 
MACRO-11 programs that have more than one entry point. 

When a program completes, it returns control to KMON 
or to any indirect file that was active when the command 
was issued to run the program. Programs may complete 
successfully, or they may stop because of an error condi- 
tion. On completion, your program can pass one or more 
command lines to KMON, which executes these com- 
mands before prompting for commands from the keyboard. 
You can also write background jobs that pass control and 
information to another job on completion. 

This chapter describes the monitor commands: GET, 
FRUN, RUN, R, START, and REENTER. The programmed 
requests and SYSLIB subroutines discussed are: .EXIT, 
.CHAIN, EXIT, SETCMD, CHAIN, RCHAIN, RAD50, IRAD50, 
and R50ASC. 
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In this chapter you will learn to restart or reenter a job. 
You will be able to write a program that passes one or more 
command lines to KMON on exiting, and you will learn to 
write two programs; the first of which executes the second 
and passes information to it. 

If you are programming in FORTRAN IV, you will write 
a program which, upon termination, exits to the monitor 
without printing any termination messages. If you are pro- 
gramming in MACRO-11, you will write a program that can 
be reentered. 


Starting Execution 


When you execute a program using the RUN or R com- 
mand, execution starts at the transfer address. In MACRO— 
11, this is the address specified as the argument to the .END 
directive in your main module. In FORTRAN IV, it is the 
address of the first instruction in the main program. 

When the program is linked, the transfer address is 
stored in word 40 of the load module file. When the pro- 
gram is loaded into memory, this address is in word 40 of 
the system communication area (SYSCOM). You can change 
the transfer address of a program written in either MACRO— 
11 or FORTRAN IV by specifying the /TRANSFER option 
when the program is linked. 


Starting Foreground Jobs 


RT—11 supports only one way of starting a foreground job— 
the FRUN command. This loads the program into memory 
and starts execution at its transfer address. Options to FRUN 
include /BUFFER:n (reserves extra space in memory), 
/NAME:name (assigns a logical name to the foreground job), 
and /PAUSE (allows you to debug a program). 
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Starting Background Jobs 


The 
jobs 


RUN command is normally used to load background 
into memory and start execution at their transfer ad- 


dress. You can separate the tasks of loading and executing 
by issuing a GET command followed by a START. These 
commands can be useful if you are debugging the program 
or if you want to run the same job several times. When a 
job completes successfully, it remains in memory until you 
load another program with RUN or GET. You can execute 
the job again using the REENTER or START command. 
These commands have the following features: 


You 


RUN loads a background program into memory, from 
the specified device (default DK:), and starts execu- 
tion at the transfer address. 


R is similar to RUN, except that it can only load the 
program from the system device because it is not ca- 
pable of loading any other device handlers. 


GET loads a program into memory but does not start 
execution. 


REENTER starts execution at the reentry address, 
which is the transfer address minus two (bytes). You 
can REENTER a program only if it sets bit 13 of the 
JSW and then exits normally (exiting is discussed 
later). You can use this command to place a second 
entry point in MACRO—11 prés#ms. This command 
is less useful if you are programming in FORTRAN 
IV because you cannot control where instructions are 
placed when the program is linked. 


START starts execution at the specified address. If no 
address is given, it starts at the transfer address. 


use START instead of RUN when: 


You want to execute a program several times. (Saves 
the time needed to fetch the program from disk for 
each execution.) 
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¢ You want to use data created during the first execution. 


¢ You want to debug your program using the methods 
discussed in chapter 4, ‘“‘Debugging Programs,” of 
Programming With RT-11, Volume 1. 


In the following example, the normal transfer address 
is at the label START, and the reentry address is the branch 
instruction. 


eh ee pe PT Ee RAMA EP SPRAINED MERA OR A SEE NEM ORR LN RTE NNO SEASON EME ON NERO ECE SOMONE EE LORE EEE NESE MCLEE TES ONE ERS pecan 


BR ENTRY2 ;Reentry point 
START: ;Initial entry point 


Initialization code 


ENTRY: 


Common code 


sseamaenges geen nace tee erence get ANE cnt 


bates \ 
“.END = START | | 


Bi bebo i ei a IN tii Si AS ABs BX SiS al ni ini inner pe 


If you want to have more than two entry points, you 
must use START and specify the address for each entry point 
(from the load map). Certain restrictions apply when you 
use these commands with overlaid programs or programs 
that use extended memory features. For details about these 
commands, refer to chapter 4 of the RT—11 System User’s 
Guide. 


Exiting 


Exiting is the process of terminating a program and return- 
ing control to the monitor. All user programs should exit 
correctly when they have completed processing. They 
chould not be allowed to loop infinitely or halt the system. 
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After your program has properly exited, you can proceed 
~ with other work. 


Exiting from MACRO—11 Programs 


To terminate a MACRO-11 program, you use the .EXIT 
programmed request. Your program can perform either a 
normal exit or a RESET operation (if you are using the SJ 
monitor), depending on the contents of RO when you issue 
the .EXIT request. 


e If RO is set to a value other than zero, a normal exit 
is performed. Mark time requests are cancelled and 
I/O operations are allowed to complete. 


¢ If RO is set to zero, a RESET operation is performed. 
Marked time requests are cancelled and J/O opera- 
tions are aborted. Under SJ, this operation is per- 
formed by the PDP—11 RESET instruction. 


If your program recognizes that a significant error has 
occurred during execution, it should clear RO on exit so that 
the program cannot be restarted. 


Exiting from FORTRAN IV Programs 


You can exit from a FORTRAN IV program in two ways: 


first, by issuing a STOP command, which prints a message 
like: 


STOP ‘text’ 


at the terminal when the program exits. 

The second way is to call the EXIT subroutine. This 
subroutine is in the FORTRAN IV subroutine library, which 
is usually combined with SYSLIB. EXIT does not display 
any termination messages. The format is: 


CALL EXIT 


42 


Programming with RT—11 


The. type of exit performed by a FORTRAN IV pro- 
gram is determined by the FORTRAN IV OTS. A normal 
exit is performed unless the OTS recognizes that a fatal er- 
ror has occurred, in which case the program stops with an 
error message. 


Passing Commands te KMON 


When a background program exits, control returns to KMON, 
which is then ready to accept more monitor commands, 
either from the keyboard or from any active indirect file. 
Your program can optionally pass one or more monitor 
commands to KMON when it exits. These commands are 
executed before any more commands are read from the 
keyboard or indirect file. 


Passing Commands from MACRO-—11 Programs 


To pass command lines to KMON when your program ex- 
its, perform the following steps: 


1. Move the command lines into locations 512 to 777 
(octal). Each command must be terminated by a null 
byte (that is, an ASCIZ string). 


2. Place a count of the number of bytes in the command 
lines into the word (not byte) at location 510 (octal). 


3. Set bit 11 of the JSW (the “‘pass line to KMON bit’’) 
immediately before the .EXIT request. 


4. Issue the .EXIT with RO=0. 


Passing Commands from FORTRAN IV Programs 


The SETCMD programmed request is used to pass a com- 
mand line to KMON from a FORTRAN IV program on exit. 
Note the following points: 
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1. Only one command line can be passed to KMON 
from FORTRAN IV programs. If you want to pass 
more than one command, make an indirect command 


file and pass a command to KMON to execute this 
file. 


2. If you pass any command lines to KMON, any indi- 
rect files that were active at the time your program 
was invoked are aborted. 


3. The argument to SETCMD can be either a quoted 
string, or a variable or array name. The command 
line must be terminated by a zero byte (ASCII null). 
(This is the equivalent of a MACRO-11 ASCIZ 
string.) If you use the normal FORTRAN IV OTS in- 
put statements (READ, ACCEPT) to read in the com- 
mand line, then you must put this byte in the string 
yourself. There are also programmed requests for ter- 
minal input which automatically place a zero byte at 
the end of the string. These are discussed in chapter 
13, “Using Multiterminal Input/Output.” 


Chaining 


When you design applications programs, you may find it 
necessary or desirable to split a programming task into two 
or more programs. You may want to do this if one program 
performing the complete task is too large to fit into mem- 
ory, or if some parts of a program are not needed every time 
the program is run. 

If you create two or more related background jobs to 
do a single programming task, you will find it useful to make 
one job capable of starting the other without operator ac- 
tion. It is also useful for the first job to be able to pass in- 
formation to the second without having to write the infor- 
mation to disk. 

RT-—11 allows you to transfer control from one pro- 
gram to another by a process called chaining. The area that 
contains the information you pass from one job to another 
is called the chain information area, and it occupies loca- 
tions 500 to 777 (octal). You should not rely on any other 
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locations being preserved from one job to the next. In vir- 
tual programs run under the XM monitor, locations 500 to 
777 are not saved, so jobs cannot be chained. Privileged 
programs under XM can, however, chain. 

Notice that location 1000 (octal), which is the top of 
the chain area, is also the default initial value of the stack 
pointer in background jobs. If your program needs a lot of 
stack space and, in addition, you want to place informa- 
tion into the chain area at compile time, this might result 
in the stack and the chain information overlapping. To avoid 
this, assign more space to the stack, using the methods de- 
scribed in chapter 1, “Developing Programs in MACRO-11 
and FORTRAN IV,” of Programming with RT—11, Volume 1. 


Chaining in MACRO—11 Programs 


To enable an outgoing job to chain to an incoming job and 
pass information to it, you should perform the following 
steps. Place the file specification (in RAD50 format) for the 
incoming job into bytes 500 to 507 (octal) of the outgoing 
job. (Read the section, ‘Using RAD50 File Descriptors,” later 
in this chapter to learn how to do this.) Then, move the in- 
formation that you want to pass to the incoming job into 
locations 510 to 777 (octal). You should use the .PEEK and 
-POKE programmed requests to access locations in the chain 
area. In the following example, the code moves the data from 
BUFF into the chain area. The format of the file specifica- 
tion is explained later. 


eircom aI teeter mn pr ret yen gf MgO A nh i nyse eto po SRS NN oe 


EXAMPLE 
MOV -#BUFF,R1 =——s; Buffer address to R1_ 
icsaee 8 MOV S#500,R200 -S (Start of chain area é 
~10$:  ««POKE = #AREA,R2,(R1) — ;Put word of data from 
TST... CR22+ = =————s«g Buff into chain area 


22TST RD Eee 


anu 3Increment pointer: 
1.08 eel. 


sBack if not done yet ~ 
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6 
| 

S BUFF: -RADSO /DK FRED SAV/ ;RADSO file spec for 
: ;DK:FRED.SAV 


»~WORD 41,2,3,4,...,0/ ;Data for next job 


Finally, issue the .CHAIN request, as follows: 


| »~ CHAIN ;Chain to next program 
t 


ane mara assim una arene miAcebeehinaniaernnntn naw iniale Rinna hi tiene iittala NBN Ao 6 Yate LS nb Saunt eet Wankimanenon entninsothdsnininanemuineanidinntbcen amine eta 


In the incoming job, test bit 8 of the JSW (the chain 
bit). It will have been set only if the program has been suc- 
cessfully chained. In this case, retrieve the information 
passed by the outgoing job from locations 510 to 777 (oc- 
tal). Use .PEEK to access this information. 

The incoming job does not have to accept information 
passed by the outgoing job. If you want to set up the chain 
area with constant data in your program, you must set bit 
8 in word 44 of block 0 in the program’s save image file. If 
you do not set this bit and the chaining occurs, bytes 500 
to 777 are saved from the job that issued the .CHAIN in- 
stead of being loaded from the save image file. To set bits 
or change other locations in your save image file, use a 
.ASECT directive in your source program. 


prone enn reenter et ener 
| 

i EXAMPLE 

| sASECT s;Word 44. CJSW) 

=44 

i JSW: - WORD 400. 3;Set bit 8 to protect 

| s;chain-area Call other 

s;bits are cleared) 

i ~=500 ;Start of chain area 

CAREA: 

t 

i e 

I PSECT 

Sanaa a Raa CARAT RAO atee RE WEY Reema TL mee Teton E 


This code sets bit 8 of word 44 (octal) and places informa- 
tion in the chain area to assure that these locations are 
loaded from the save image file. You can use the same 
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method to set other bits, or a combination of bits, in the 
load image. 


Chaining in FORTRAN IV Programs 


To enable the outgoing job to chain to an incoming job and 
pass information to it, you should place the file specifica- 
tion (in RAD50 format) for the incoming job into a four-word 
area of the outgoing job. (Read the section, ‘““Using RAD50 
File Descriptors,” later in this chapter to learn how to do 
this.) Then place the information (up to 60 words) that you 
want to pass to the incoming job, into an array or sequence 
of variables in a COMMON block. The first variable must 
start on a word boundary. Finally, call the CHAIN subrou- 
tine. The format is: 


CALL CHAIN (dblk,var,went) 
In this statement: 


dblk is the address of the area containing the device 
and file specification of the incoming job 


var is the address of the first variable containing the 
information to be passed 


went _ is the number of words of information (beginning 
at var) to be passed, which must not exceed 60 


In the incoming job, call the RCHAIN subroutine to see 
if this job has been chained to the outgoing job. The format 
is: 


CALL RCHAIN (flag,var,wecnt) 


If it has been chained, the integer variable ‘‘flag”’ is set to 
—1 (true). If not, ‘flag’ is 0 (false). 

If the program has been chained, RCHAIN also re- 
trieves any information passed by the outgoing job. “‘var’’ 
is the address of the first of a sequence of variables where 
you want the information to be stored. You should set 
“went” to the number of words to be moved. 
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Using RAD50 Fcle Descriptors 


A MACRO-11 or FORTRAN IV program which chains to 
another job must specify the incoming job’s file specifica- 
tion in a four-word area called the file descriptor block. This 
block contains the following information: 


¢ The device type (3 characters) 
e The file name (6 characters) 


¢ The file type (3 characters) 


This information must be stored in Radix 50 (RAD50) 
format. RAD50 code allows three characters to be stored in 
each word instead of the usual two. You can use any up- 
percase alphabetic characters, numbers, and spaces (space) 
characters) in the file descriptor block. Figure 31 shows an 
example of how the file specification DK:HELLO.SAV would 
be stored. Notice that each field must be extended to its full 
length, with trailing spaces if necessary. This file specifi- 
cation would be stored as: 


DK space) 3 characters for the device name 
HELLO space) 6 characters for the file name 
SAV 3 characters for the file type 


Figure 31. 
RAD50 File Descriptor Block for DK:HELLO.SAV 


DEVICE FILE 
NAME . FILE NAME TYPE 
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If, at the time you write your program, you know the 
file specification for the job to which you want to chain, 
you can set up the file description as constant data. In MA- 
CRO-11 programs you can do this with the .RAD50 assem- 
bler directive. In FORTRAN IV programs you can use the 
R specifier in a DATA statement. 

If, for example, you get the file specification at run time 
by reading it from the terminal, you will have to convert it 
from ASCII to RAD50 code and store it in the file descrip- 
tor block. Conversion routines are provided in the system 
subroutine library. 


RAD50 in MACRO-—11 Programs 


The .RAD50 assembler directive encodes text in RAD50 
format and reserves one word of storage for every three 
characters in the text string. If the text is not a multiple of 
three characters, the directive automatically appends trail- 
ing spaces. The format of the directive is: 


FDB: .RAD50 = /text/ 


Here /(slash) may be any delimiter that does not appear in 
the text. 
You can specify the complete file descriptor block in 


a single .RAD50 directive, or you can use a separate direc- 
tive for each field. 


a ene et ee et en en eee ne ect ate tonto mtu temermim ame 
4 ‘ " 4 
2 4 


Your can Greate a file descriptor block fOr a4 
DK: HELLO. SAV in two ways: 


DBI: “Raps 10K HELLO. SAV/ ;File descriptor 


oe : sblock. -<: 4 
:F.DB2is27 -RADSO “pk Ne eee name 
/ -RADSO THELLOS 3File name ~ 


acento eet te REN SEMEL OA ER 


8 -RADSO _1SANL peeshl ve type 


ee 
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In the first method, you have to remember to include 
spaces in the text string to keep the correct word positions 
for the field. In the second method, the directive appends 
trailing spaces to the fields as necessary. If the file name is 
three characters or fewer, you must add enough spaces to 
make sure that two words of storage (not just one) are re- 
served. 


RAD50 in FORTRAN IV Programs 


You can store the file descriptor block in any set of four 
sequential words. You can use the single four-word vari- 
able (REAL*8, COMPLEX, or DOUBLE PRECISION) that is 
easiest to initialize. If you want to be able to refer to each 
word separately, use a four-element INTEGER*2 array. 

To store the file descriptor information in RAD50 code, 
use the R format specifier in a DATA statement. 


i 
2 
‘ 
i 
i 
j 
2 
{ 
cd 
j 
3 
i 
i 
{ 
i 
i 


AN PEO AN EY SRN RN DR OLEH ET eA HERO HHI SM ODN eng 


EXAMPLE 


REAL*8 FDB ie 
DATA FDB/12RDK HELLO SAV/ 4 


If you want, you can define each field separately. 


3 
i 


INTEGER#2 IFDBLKC4). 
DATA IFDBLK/2RDK,3RHEL,2RLO, 3RSAV/ 


erie ans a ea souemnebecra 


In the first example, you must include spaces as nec- 
essary so that each field occupies its full length. In the sec- 
ond example, you must define each element of the array 
separately. In either case, if the text string is not a multiple 
of three characters, the compiler appends enough trailing 
spaces to make it so. 
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1. If you are programming in MACRO-11, create the fol- 
lowing programs: | 


Program 1 (PR1001.MAC) 


-TITLE 


; PR1001 


MSGBFR: 
PROMPT: 


START: 


»-MCALL 
-ENABL 
. BLKB 
-ASCII 
- EVEN 
-GTLIN 


CLR 
~-EXIT 
-END 


PR1001 
Prompt the user to enter a command, 
read it, and exit “preventing the 


program from being REENTERed. 


-GTLIN .EXIT 


LC 
83. ;Input text buffer 
“Enter command: "<200> 


#MSGBFR,#PROMPT ;Prompt for and get 
;input string 
RO ;Clear RO for hard 


;exit and exit 
START , 


Program 2 (PR1002.MAC) 


3 PR1002 


-TITLE 


PR1002 


Announce that program 2 has 
started and then exit. 


-MCALL 
-ENABL 
-ASCIZ 
-EVEN 
-PRINT 
-EXIT 
- END 


-PRINT .EXIT 
LC 
"HI THERE! THIS IS PROGRAM 2." 


#HELLO ;Display message 
sand exit 
START 


Tailor the programs to use the extended memory fea- 
tures under the XM monitor. Use the .PEEK and .POKE 
programmed requests when you need to gain access to 
absolute locations in memory. 
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Assemble, link, and execute program 1 at your termi- 
nal. The system prompts you to type a monitor com- 
mand; you can respond by typing a command like: 


DATE 01-JUN-84 


Try to reenter the program. KMON should give you an 
error message because the program, as written, cannot 
be reentered. 


Copy program 1 into a file called PR1003.MAC. Modify 
the program in PR1003 so that it can be reentered and, 
on termination, displays a message reminding you to 
reenter the program. When you reenter, move the mon- 
itor command that you typed into the chain area and 
chain to program 2 (PR1002). Assemble and link 
program 2. 


Execute program 1 (PR1003) and type in a monitor 
command. The program should then stop. Reenter it, 
and check that you get a message announcing that pro- 
gram 2 has started. 


Copy program 2 into a file called PR1004.MAC. Modify 
it so that it checks whether it has been chained. If it 
has not, it should issue an error message and stop. If it 
has, it should pick up the monitor command from the 
chain area, move it into the parameter area for KMON, 
and pass the command to KMON on exit. 


Modify program 1 to chain to PR1004. Execute pro- 
gram 2 and check to see that it gives the error message. 
Now execute program 1 and reenter it. Check to see 
that the monitor command you typed in is passed to 
KMON by program 2 and executed correctly. 


SYSLIB Routines for RAD50 Conversion 


If you do not know the file specification until run time, you 
will have to convert it from ASCII to RAD50 code using the 
conversion routines available in SYSLIB. These conversion 
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routines are available to both MACRO—11 and FORTRAN 
IV programmers: 


¢ IRAD50 converts a specified number of ASCII charac- 
ters to RAD50 


¢ RAD50 converts six ASCII characters to RAD50 


Practice . If you are programming in FORTRAN IV, create the 
10—2 following programs: 


Program 1 (PR1001.FOR) 


PROGRAM PR1001 


Prompt the user to enter a monitor command 
and then exit. 


BYTE MSGBFRC80) 

TYPE 100 ! Ask for a command 
FORMAT €1H$,’Enter command: ‘’) 

ACCEPT 101,MSGBFR ! Read command line 
FORMAT C80A1) 

STOP “END OF PROGRAM’ ! Exit with mesaage 
END 


Program 2 (PR1002.FOR) 


PROGRAM PR1002 


Announce that program 2 has started and then 
exit without a message. 


TYPE 100 

FORMAT C1H ,’HI THERE! THIS IS PROGRAM 2.7’) 
CALL EXIT 

END 


Compile, link, and execute program 1 at your terminal. 
It prompts you to type a monitor command; you can 
respond by typing a command like: 


DATE 01-JUN-84 
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Notice the message displayed when the program termi- 
nates. Now modify the program so that it does not dis- 
play any termination messages. 


Copy program 1 to PR1003.FOR and modify it so that 
after it reads the monitor command, it chains to pro- 
gram 2 (PR1002.FOR) passing the monitor command in 
the chain area. Compile and link program 2. 

Execute program 1 and type in a monitor command. 


Check to see that you get a message announcing that 
program 2 has started. 


Copy program 2 to PR1004.FOR and modify it so that 


it checks to see if it has been chained. If it has not, is- 
sue an error message and stop. If it has, pick up the 
monitor command from the chain area, pass the com- 
mand to KMON, and then stop the program. 


Execute program 2 and check to see that it gives the 
error message. Now modify program 1 to chain to 
PR1004. Execute program 1 and check to see that the 
monitor command you type in is passed to KMON by 
program 2 and executed correctly. 
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Using 
Input/Output 
Systems 


Almost all programs interact in some way with one or more 
peripheral devices. This interaction is normally for the 
purpose of inputting or outputting data. Support for in- 
put/output (I/O) operations in RT-11 is provided by means 
of programmed requests which allow you to perform I/O 
operations in one of three modes—synchronous, asyn- 
chronous, or event driven. 

Synchronous I/O is processed in sequence with the 
program; that is, the program must wait for the I/O opera- 
tion to be completed before it can continue. Asynchronous 
I/O, one form of nonsynchronous I/O, is processed inde- 
pendent of the program; that is, the program can continue 
without waiting for I/O completion. Wher the program needs 
the results of the I/O request, it must wait. Event-driven I/O, 
the other form of nonsynchronous I/O, enables you to spec- 
ify a routine to be executed when the I/O is completed. 

This chapter discusses these modes of performing I/O 
as well as the support for terminal, file, and queued I/O. It 
also describes the FORTRAN IV object time system (OTS) 
I/O support. The discussion is designed to help you select 
which form of I/O to use in your programs. 


Ora 
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1/O Operations 


Programming with RT-—11 


The MACRO-11 programmed requests introduced in 
this chapter are: .TTYIN, .TTINR, .TTYOUT, .TTOUTR, 
PRINT, .GTLIN, .READ, .READW, .READC, .WRITE, 
.WRITW, .WRITC, .FETCH, .ENTER, .LOOKUP, .CLOSE, 
-PURGE, .RELEAS, .CSIGEN, .CSISPC, and .SPFUN. The 
FORTRAN IV requests introduced are: ITTINR, ITTOUR, 
PRINT, GTLIN, IREAD, IREADW, IREADC, IREADF, IWRITE, 
IWRITW, IWRITC, IWRITF, IFETCH, IGETC, IENTER, 
LOOKUP, CLOSEC, PURGE, IFREEC, ICSI, ISPFN, ISPFNW, 
ISPFNC, and ISPFNF. 


Almost every program has to perform some input or output 
operation; I/O operations are among the services most fre- 
quently used. The I/O method you choose affects both the 
ease of program writing and the execution speed. 

I/O operations are divided into two classes, synchron- 
ous and nonsynchronous. Synchronous I/O is executed se- 
rially in a program; that is, when the program issues an I/O 
request, it must wait until the I/O operation has been com- 
pleted before it can continue processing. Nonsynchronous 
I/O operations execute in parallel with the program, which 
is more efficient because the CPU can continue processing 
while a device is performing an I/O transfer. Thus, I/O and 
CPU processing can overlap, decreasing the total process- 
ing time. 

Figure 32 shows a program using synchronous I/O. The 
numbers indicate the following events: 


1 The program issues a read request and stops process- 
ing. The system processes the read request. 


2 When data is available the read operation is com- 
pleted and control returns to the user program. 


3 The program issues a write request and stops process- 
ing. The system processes the write request. 


4 The write operation is completed and control returns 
to the user program. 
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Figure 32. 
Synchronous Processing 


READ 
OPERATION 


PROGRAM 


WRITE 
OPERATION 


TIME 


Figure 33 shows a program using nonsynchronous I/O. 
The numbers indicate the following events: 


1 The program issues a read request and continues pro- 
cessing. The system processes the read request in 
parallel. 


2 The program issues a write request and continues 
processing. The system processes the write request in 
parallel to the program and the read request. 


3 The program cannot continue until the read is com- 
pleted, so it waits for I/O completion of the read 
request. 


4 The read is-completed and the system informs the 
program, which continues. 


The processing continues, with the program issuing 
nonsynchronous I/O requests and being informed of I/O 
completions as they occur. 
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1/O Modes 


Programming with RT-—11 


Figure 33. 
Nonsynchronous Processing 


READ 4 
OPERATION 


PROGRAM 


WRITE 
OPERATION 


TIME 


RT-—11 programmed requests support both synchronous and 
nonsynchronous I/O operations. Nonsynchronous opera- 
tions can be further divided into asynchronous and event- 
driven modes. Thus, the two classes of RT—11 I/O opera- 
tions include three different modes. These modes are re- 
lated as shown in figure 34. Using these processing modes 


you can maximize performance under many different con- 


ditions. 


Synchronous mode 


When a synchronous I/O operation is requested, program 
execution is suspended until the I/O transfer is completed. 
This is the easiest mode to program, but it is the most in- 
efficient method because there is no overlap of CPU and I/O 
processing. 
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Figure 34. 
RT-11 Input/Output Modes 


1/0 MODES 


SYNCHRONOUS NON-SYNCHRONOUS 


ASYNCHRONOUS EVENT-DRIVEN 


Asynchronous mode 


When an asynchronous I/O operation is requested, pro- 
gram execution is suspended only until the monitor has 
queued the request. The program then continues execu- 
tion, possibly before the I/O has been completed. It contin- 
ues processing until it needs to synchronize with the I/O 
operation, for example, to use the data received. At this time 
the program must test for I/O completion with the .WAIT 
request. 


Event-driven mode 


When a program requests an event-driven I/O operation, the 
monitor suspends program execution until the request has * 
been queued. The program then continues executing, pos- 
sibly before the I/O has been completed. When the I/O is 
completed, the monitor interrupts the main program and 
executes a completion routine, specified in the original I/O 
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request. This routine can be used to perform any process- 
ing that had to wait for I/O completion. 

The event-driven mode is the most efficient method of 
overlapping I/O and CPU processing because the program 
does not have to test for I/O completion before executing 
code that must be synchronized with the I/O transfer. It is, 
however, the most difficult to implement. 


Selecting an I/O Mode 


The careful selection of I/O modes will help you achieve 
high performance from a program that includes large 
amounts of both I/O operations and CPU processing. Non- 
synchronous IJ/O is most effective when the program is di- 
vided into a number of processes. For example, reading a 
buffer, analyzing the data, and writing a buffer can each be 
a separate process. These processes can run concurrently, 
but they need to be synchronized. The program must not 
try to analyze the data before it has been read into the buffer. 
Throughput is most efficient when there is a maximum 
overlap of process activity. 

The following suggestions should help you select the 
best I/O mode to use for your applications programs: 


1. If performance is not important, use synchronous 
mode because it is the simplest to program. 


2. If one process needs much more time than the others, 
use synchronous mode because the potential overlap 
is small. 


3. If system performance is important and the task can 
be divided into a number of processes whose timing 
is random, use event-driven mode. This gives the 
most efficient overlap of I/O and processing. 


4. If the time required for a process is comparatively 
long, use event-driven I/O. For example, consider an 
application with a number of input devices. The ap- 
plication software is designed to accept input from 

any of them, process the data, and output the results 
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to a data base. At any given time, a device may have 
no operator or may not be working. The system must 
not hang waiting for input from any of the devices, 
so event-driven I/O is the only practical choice. 


5. If none of the above apply, consider using asynchron- 
ous mode to overlap the longest processes. The I/O 
and .WAIT requests should be arranged to keep these 
processes as active as possible. 


Terminal I/O 


The console terminal is the most frequently used periph- 
eral device because almost all programs send and receive 
data through it. RT—11 has a set of programmed requests 
developed expressly for console terminal I/O. These re- 
quests are listed in table 8. The system code for all these 
requests (except .GTLIN or GTLIN) resides within RMON. 
(The .GTLIN or GTLIN requests require the USR.) This 
means that terminal I/O does not need any disk access to 
load additional system software. 

The terminal I/O system structure is shown in figure 
35. When a terminal I/O request is issued, the EMT dis- 
patch routine passes the request to the terminal service 


Table 8. 
Terminal I/O Requests 

MACRO-11 FORTRAN IV 
Operation Requests Requests 
Input character .TTYIN ITTINR 
from terminal TTINR 
Output character -TTYOUT ITTOUR 
to terminal TTOUTR 
Input line from -GTLIN GTLIN 
terminal 
Output line to .PRINT PRINT 


terminal 
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Figure 35. 
Processing Terminal Input/Output Requests 
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routines. These routines gain access to the terminal device 
registers directly. 


When your program needs to communicate with the 


terminal, first consider using the terminal I/O requests since 
they are fast and flexible. Also, they do not greatly increase 
the size of your program because the code needed to exe- 
cute them is always in memory, as part of RMON. The dis- 
advantages of using the terminal I/O requests are: 


The requests are device specific. If you later decide 
to send your output to a line printer, you must re- 
write part of your program. If you want to be able to 


change the I/O device easily, use one of the other I/O 


systems. 


Terminal I/O transmits data in character format only. 
Your program must perform any conversions, for ex- 
ample, binary to ASCII. If a FORTRAN IV program is 
to send out numeric data, you should consider using 
I/O statements in FORTRAN IV format. 
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Table 8 lists a complete set of programmed requests that 
permit multiterminal I/O. These requests are discussed in 
chapter 13, ‘Using Multiterminal Input/Output.”’ 


Queued I/O 


RT-11 provides a standard programming interface for ac- 
cessing the supported devices (such as storage disks and 
printers) and for special programs (called device handlers) 
which control each device. The interface takes I/O requests 
from user programs and puts them on a queue to be pro- 


‘cessed by the appropriate device handler. This process is 


called queued I/O. The requests used to perform input and 
output through queued I/O are listed in table 9. 

The system device handler and system code reside in 
memory under all three monitors. The handler for the con- 
sole terminal is resident in memory under the FB and XM 
monitors. Under the SJ monitor, it resides on the system 
disk and is loaded by the USR when needed. To decrease 
memory requirements, all other device handlers reside on 
the system disk and are loaded into memory when needed. 

The common code needed to transfer information be- 
tween a peripheral and a running program is in the Resi- 


Table 9. 
Queued I/O Requests 
MACRO-11 FORTRAN IV 

Operation Requests Requests 

Input from .READW IREADW 

peripheral READ IREAD 

Seyice -READC IREADC 
IREADF 

Output to .WRITW IWRITW 

peripheral WRITE IWRITE 

eeuce WRITC IWRITC 


IWRITF 
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dent Monitor RMON. When a queued I/O request is issued, 
RMON passes this request on to the appropriate device 
handler, using a data structure called an I/O queue ele- 
ment. Figure 36 shows the flow for queued I/O requests. 

The flexible options of the queued I/O system make it 
the logical choice for I/O to most devices. As a program- 
mer, you do not need to know very much about the device 
being used. The programs written using queued I/O can be 
device independent, and you can determine the actual de- 
vice to be called at execution time. 


File /O 


Certain set-up operations are required before you perform 
queued I/O to a file, and some clean-up operations are also 
required once I/O is completed. Table 10 shows the se- 
quence of operations for MACRO-11 and FORTRAN IV files. 

These requests need the file and device specifications 
in a device block in RAD50 format (see chapter 10). Pro- 


Figure 36. 
Processing Queued Input/Output Requests 
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Table 10. 
Sequence of Operations and Requests for File !/O 
MACRO-11 FORTRAN IV 
Operation Request Request 
1. Load the device FETCH IFETCH 
handler 
2. Allocate a channel IGETC 
to a device 
3. Open the channel ENTER IENTER 
LOOKUP LOOKUP 
4. Perform I/O -.READ IREAD 
WRITE IWRITE 
5. Close or purge the .CLOSE CLOSEC 
channel PURGE PURGE 
Free the channel IFREEC 
Release the handler -RELEAS 


grams that need to read ASCII file specifications from the 
console terminal or indirect command files can use the 
Command String Interpreter (CSI). Table 11 lists the re- 
quests used to process an ASCII string in CSI format. These 
set-up and clean-up requests are executed by the USR 
monitor component. The USR may be either memory or disk 
resident. Swapping the USR is covered in chapter 18, ‘‘Us- 
ing Memory.” 


Table 11. 

Requests for Processing ASCIl Strings in CSI Format 
MACRO-11 FORTRAN IV 

Operation Request Request 

Load handlers and open .CSIGEN 

channels 

Return RAD50 device .CSISPC ICSI 


blocks 
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Special Function I/O 


RT—11 provides a special function I/O request that permits 
a program to perform device-dependent operations in all 
three I/O modes, on magnetic tapes and on some disks. 

If you are programming in MACRO-11, you should use 
the request .SPFUN and specify the I/O mode in an argu- 
ment to the macro call. If you are programming in FOR- 
TRAN IV, you can use one of four functions, ISPFN, 
ISPFNW, ISPFNC, or ISPFNF, for each of the different I/O 
modes. 


FORTRAN IV OTS I/O 


The FORTRAN IV language provides support for I/O through 
the statements, READ, WRITE, TYPE, ACCEPT, and PRINT. 
Because they are a defined part of the language, with no 
special subprogram calls needed, the following features al- 
low for easy handling of data input and output: 


e The division of I/O information into records 


e Automatic translation between character and internal 
representation using formatted I/O 


e Direct or random access I/O 


Most common I/O operations to the terminal and other 
devices can be performed using these statements. How- 
ever, these statements do not provide all of the capabilities 
of the RT-—11 programmed requests. Because of the way in 
which the FORTRAN IV OTS performs I/O, the use of pro- 
grammed requests can increase the execution speed and 
decrease the size of your program. The OTS I/O mecha- 
nism is showr in figure 37. 

When a FORTRAN IV program executes an I/O state- 
ment, it calls some OTS routines. The OTS responds by ex- 
ecuting RT—11 programmed requests. These may be termi- 
nal I/O or queued I/O requests, depending on the device 
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Figure 37. 
Performing Input/Output through FORTRAN IV OTS 


PROGRAMMED 
REQUESTS 


FORTRAN 1/0 
STATEMENTS 


USER 
FORTRAN 
PROGRAM 


‘assigned. The OTS does not perform direct I/O itself but 
passes all requests to RT—11. 

If your program uses programmed requests, you are able 
to bypass the I/O routines, communicating directly with RT— 
11. This reduces the time required to process OTS I/O rou- 
tines, so your program should execute faster. If you remove 
all uses of one or more classes of FORTRAN IV J/O (for ex- 
ample, all formatted or direct I/O statements), the corre- 
sponding OTS routines will not be linked with your pro- 
gram, making it smaller. 


Reference 


RT—11 Programmer’s Reference Manual. Chapter 1 discusses 
input/output operations, terminal input, output, and multiter- 
minal requests. 


Terminal I/O Buffers ~ 
Special Characters 
Single-Character I/O 


MACRO—11 Requests: .TTINR, .TTOUTR, .TTYIN, 
and .TTYOUT 


FORTRAN IV Requests: ITTINR and ITTOUR 
Error Handling under the SJ Monitor 
Error Handling under the FB Monitor 
Overriding Job Blocking under the FB Monitor 
Setting Up and Using |/O Buffers 
Terminal Special Mode 
Line-oriented Output 
Using .PRINT in MACRO-—11 
-PRINT from a Foreground Job 
Using PRINT in FORTRAN IV 
Line-oriented Input 
Input from Indirect Command Files 
Handling (CcTRUC) 
Handling (CTRUO) 
Reference 


Using 
Terminal 
Input/Output 


In most applications, you interact with a program through 
the console terminal. The program sends messages, ques- 
tions, warnings, and prompts to the terminal and receives 
responses to questions, choices of options, and commands 
from the terminal. 

Information is transferred in both directions as a se- 
ries of characters. Digital’s systems use the seven-bit ver- 
sion of the American Standard Code for Information Inter- 
change (ASCII). Most ASCII characters are standard printing 
characters such as numbers, letters, and punctuation marks. 
Some special nonprinting characters are used for control- 
ling the terminal and sending special signals to the pro- 
cessor. | 

The basic operations of terminal I/O are single-char- 
acter input and output. There are also line-oriented I/O 
functions in which a whole line is transferred by one pro- 
grammed request. Other features offered by RT—11 for ter- 
minal I/O include the ability to enable or suppress echo 
printing and handle the special characters (ctrucy and 


(CTRUO). 

This chapter describes how to use the programmed re- 
quests: .TTINR, .TTYIN, .TTOUTR, .TTYOUT, .PRINT, 
.GTLIN, .SCCA, and .RCTRLO for MACRO-11 and ITTINR, 
ITTOUR, PRINT, GTLIN, SCCA, and RCTRLO for FOR- 
TRAN IV. 
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When you have completed this chapter, you will be 
able to write code to transfer a line of text from the termi- 
nal to a buffer in memory, using the single-character input 
requests .TTYIN for MACRO-11 and ITTINR for FOR- 
TRAN IV. You will also learn to perform the following 
functions: input text from the terminal; print text from a 
buffer in memory on a terminal, using the output requests 
.TTYOUT and .PRINT for MACRO-11 or ITTOUR and 
PRINT for FORTRAN IV; prevent cctrauc) from aborting a 
program; and reset (ctruoy) under program control. 


Terminal I/O Buffers 


Terminal I/O in RT—11 is performed through a set of buffers 
known as the terminal I/O buffers. Each job has two buffers, 
one for input and one for output, both located in the job’s 
impure area. By using the terminal I/O requests, you can 
transfer characters between a program and its terminal I/O 
buffers. 

Interrupt service routines in RMON handle the actual 
character transfer between the I/O buffers and the terminal. 
By handling the transfer on an interrupt basis, RMON al- 
lows terminal I/O to run in parallel with the user program. 
On input, parallel processing means that you can type in 
characters before the program asks for them. This is known 
as type-ahead. On output, parallel processing means that the 
program can issue a number of output requests and can 
continue running while the characters are being printed. 
Thus, the program can run more quickly since it does not 
need to wait for all the characters to be printed before it 
proceeds. 

Normally RMON does not make input characters 
available to your program until you type a line-terminating 

_ character, such as (RETURN), (LINEFEED), (CTRUZ), OF in some cases 
(ctruc). This means that the characters are held in a buffer, 
and you can correct typing errors, using the line-editing 
characters (oevete) and (ctruu). 

The internal structure of the terminal I/O system is 
shown in figure. 38. The arrows indicate the transfer of a 
character between the terminal and the program. Notice that 
the path for input is independent of the path for output. 
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Figure 38. 
Internal Structure of the Terminal Input/Output System 
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Special Characters 


Certain characters are not passed through the terminal in- 
put buffer by the terminal service routines. These charac- 
ters include: 
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e Line-editing characters (peete) and (ctrvu) 
¢ Terminal control characters (ctrvo), (ctrus), and (cTRvo) 


e Characters to direct terminal input under the FB and 
XM monitors (ctrury and (ctrve) 


e Characters for use when system job support is en- 
abled (ctrux) 


e Interrupt character (ctave) 


By default, all of these are handled by RMON. Techniques 
for inhibiting (ctruc) and resetting (ctruoy are discussed later 
in this chapter. | 

Another input character that is handled specially is the 
carriage return. When you press return), the input terminal 
service routine always inserts both a carriage return and a 
line feed into the terminal input buffer. 


Single-Character I/O 


Some of the programmed requests supported by RT—11 for 
terminal I/O will only operate on a single character. These 
requests can be used to retrieve one character from the ter- 
minal input buffer or add one character to the terminal 
output buffer. 


MACRO—11 Requests: .TTINR, .TTOUTR, 
«TTYIN, and .TTYOUT 


-TTINR moves a single ASCII character from the terminal 
input buffer to the low-order byte of register RO. .TTOUTR 
moves a single character from the low-order byte of RO into 
the terminal output buffer. .TTINR and .TTOUTR do not take 
any arguments. 

These requests each have a single possible error re- 
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turn. .TTINR returns an error if no character is available in 
the terminal input buffer. .TTOUTR returns an error if there 
is no room in the terminal output buffer for the character. 
The purpose of these two requests is to attempt the I/O op- 
eration, and return an error immediately if the operation is 
not possible at the time of the request. 

The more common form of terminal I/O is the use of 
-TTYIN and .TTYOUT. These requests are similar to .TTINR 
and .TTOUTR, except that they loop, repeating the request 
until a terminator has been typed and the operation can be 
completed. These requests take an optional argument; for 
.TTYIN, the address of where to put the character, and for 
.TTYOUT, the address of the character to be output. 


FORTRAN IV Requests: ITTINR and ITTOUR 


ITTINR gets a character from the terminal input buffer and 
returns the ASCII code for the character as its function code. 
A negative value indicates that no character is available in 
the terminal input buffer. The function is called using the 
format: 


ICHAR =ITTINR() 


There are no arguments to ITTINR, but the parentheses are 
required so the compiler can tell that ITTINR is a function 
reference, not a variable reference. 

The result of ITTINR must first be placed in an INTE- 
GER variable to check for an error return. If there is no er- 
ror, you can transfer it to a BYTE (or LOGICAL*1) variable. 
This sequence is necessary because for negative numbers 
the PDP—11 sets the highest bit (bit 15) to 1. To test whether 
the result of ITTINR is negative, the processor tests bit 15 
of the returned variable. If you place the result in a BYTE 
variable, only the low-order eight bits are stored. The high- 
order bits, including bit 15, are lost. If you then try to test 
for errors by seeing whether the BYTE variable is negative, 
you will receive incorrect results. 
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The following example shows the correct use of IT- 
TINR and the test of its returned value: 


| EXAMPLE ee 
: BYTE CHRTRS(80) 
INTEGER RETVAL ~ 


4 
Simi ak ic et sina IB aig Son ad 


| “DD? 10-1 =4580 tee ae ane ae 
221002 RET VALS FELINRO) <0 ee es ees 
ee oe DE OCRETVALS EE 09° GO8TO 2100 sie ad 
e/a CHRTRS CL) GRETVAL LGAs ger Dace 4 
10 CONTINUE © ee eee 
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ITTOUR is the programmed request to output single 
characters. It takes a single-byte variable as an argument and 
transfers the character in that byte to the terminal output 
buffer. A return value of one from ITTOUR indicates an er- 
ror, namely, that there is no room in the terminal output 
buffer for the character. 


Error Handling under the SJ Monitor 


The SJ and FB monitors handle terminal I/O error condi- 
tions differently. The SJ monitor always returns an error code 
to the user program if an error condition exists. On input 
the only error is “‘no character available in the buffer,’’ and 
on output the only error is ‘‘no room in the buffer.’’ Your 
program must check the error indicator and take appro- 
priate action. Usually the appropriate action is to retry the 
request by looping again until the transfer is successful. In 
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MACRO-11 programs you can do this by using the .TTINR 
or .TTOUR request. 


EXAMPLE 


-MCALL .TTINR 


1$: -TTINR ;Try to read a character 
BCS 1$ ;Repeat if none ready 


;Continue when success 


Hectetediteetotaetinint Lh in atinntietimh teaiineddane me ice ie tut i mianlnitid 
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The programmed requests .TTYIN and .TTYOUT per- 
form the looping for you. Neither proceeds until the I/O re- 
quest has executed error-free. Also, with these requests you 
can give an argument that specifies the location of the data 
to be transferred. You should use .TTYIN and .TTYOUT 
unless you want to do some other processing before retry- 
ing the request. 

In FORTRAN IV programs you can test for errors and 
retry the request by examining the return value from the 
ITTINR and ITTOUR functions, and by looping if an error 
exists. 


EXAMPLE 


2 ICHAR=ITTINRC) 
IF CICHAR.LT.0) GO TO 5 


or 


Sicko a eaaatila lesan nina teeta canna R ESE Senate sbteinanier eis anand 


10 IF CITTOURCCHAR).NE.O) GO TO 10 
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Always use a loop like one of these if you do not want your 
program to proceed until the I/O request has executed suc- 
cessfully. 
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Error Handling under the FB Monitor 


Normally, when you issue a terminal I/O request, you do 
not want the program to continue before the transfer is 
complete. Under the SJ monitor you can ensure comple- 
tion of transfer by looping to repeat the request until it re- 
turns a success indication. Looping works well for a sys- 
tem like SJ where only one job can run at a time. Under the 
FB monitor, however, you can run two jobs at a time. When 
one job is waiting for I/O completion, the other can be al- 
lowed to run. If the I/O request loops, as under SJ, then the 
monitor cannot tell that it could be running the other job. 
Therefore, the FB monitor uses a different technique for 
handling I/O requests. 

A job waiting for some specific I/O condition to occur 
is said to be blocked. When a job is blocked the FB monitor 
switches control to a job that can run. Jobs are assigned rel- 
ative priorities, and FB always selects the highest priority 
job that is not blocked. 

The terminal I/O service routines under FB automati- 
cally block a job that issues a terminal ‘I/O request if the 
request cannot be completed immediately. The job remains 
blocked until the condition is cleared and the FB monitor 
can schedule it to run. 

One effect of this blocking technique is that the .TTINR 
or ITTINR and .TTOUTR or ITTOUR requests do not return 
an error code. The job is blocked until the transfer is com- 
plete. This means that under the FB monitor .TTINR be- 
haves the same as .TTYIN, and .TTOUTR behaves the same 
as .TTYOUT. If you use .TTINR or ITTINR or .TTOUTR or 
ITTOUR, you should check for the error code to ensure that 
the program will run correctly, even under the SJ monitor. 


Overriding Job Blocking under the FB Monitor 


You may not want your job to be blocked by the monitor 
when you issue a .TTINR/ITTINR or .TTOUR/ITTOUR pro- 
grammed request. If you want to get an error code and pro- 


gram your own response, as under the SJ monitor, set bit 6 
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of the job status word (word 44 in the system communica- 
tion area) before issuing the I/O request. 


EXAMPLE 


In FORTRAN IV use the command: 


! In MACRO—11 use the statement: 


| 
CALL IPOKE €"44,I1PEEKC"44).0R."100) 
BIS #100,@#44 ;Set bit 6 of JSW | 


Basic dint Wine Minin iN RN A NN CH NCS inane AIL tS Nt ace NUNCA HOM ante tien RU aba eS abe a ona Rent gn gv Aas 


clear it. 


~ EXAMPLE | 
In FORTRAN IV use the command: | : 
| ~ CALL IPOKE (44, IPEEKC''44). AND. .NOT."100) 

be In MACRO—11 use the statement: 


| 
: 
BIC #100,@#44 ;Clear bit 6 of JSW 
j 


einai sth annette stcnnsans sees etic nda abt sauna hm isnanntoneniecli Keenan Site simabationitiooanatind 


Do not use this technique if you intend to loop (or in MA- 
CRO-—11 use .TTYIN or .TTYOUT), because it prevents any 
background job from running. 

You should reset (ctrvoy after setting or clearing any bits 
in the JSW, and before issuing the first terminal I/O re- 
quest. This forces the monitor to update all the terminal data 
structures with the new status. The programmed request to 
reset ctrvo) is discussed later in this chapter. 

Table 12 shows the RT—11 processing schemes for ter- 
minal I/O when transfer of a character cannot take place. : 
Error handling under the SJ monitor is not affected by the 
value of bit 6 of the JSW. Table 13 shows how to program 
terminal I/O, either to wait for completion of error process- 
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ITTINR 
ITTOUR 


Program continues processing 


Program must check for error 


Table 12. 
Terminal I/O Error Processing Schemes 
.TTYIN .TTINR 
Monitor .TTYOUT .TTOUTR 
SJ-FB,XM with C-bit is set C-bit is set 
bit 6 of JSW Program loops 
set 
FB,XM with Job blocked Job blocked 
bit 6 of JSW Control passes to Control passes to 
clear lower priority job lower priority job 


ing, or to allow the program to continue if error occurs. If 
you leave bit 6 of the JSW clear, the job will be blocked 
until I/O completion. You should still test for errors and loop 
to retry the request, so that the program can run correctly 
under the SJ monitor. You leave bit 6 set only when you 


Table 13. 


Techniques for Handling Terminal I/O Errors 


Monitor Language 


SJ MACRO-11 
FORTRAN IV 


FB,XM MACRO-11 


FORTRAN IV 


Program Waits until 
Error Condition 
Is Cleared 


Use .TTYIN and 
.TTYOUT 

Use ITTINR and 
ITTOUR; loop 
until error 
condition clears 


Clear bit 6 of JSW; 
Use .TTYIN and 
-TTYOUT 

Clear bit 6 of JSW. 
use ITTINR and 
ITTOUR 


Program Continues 
if an Error Occurs 


Use .TTINR and 
.TTOUTR 


Use ITTINR and 
ITTOUR 


Set bit 6 of JSW; 
use .TTINR and 
.TTOUTR 

Set bit 6 of JSW; 
use ITTINR and 
ITTOUR 
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need to continue processing, even if .TTINR and .TTOUTR 
or ITTINR and ITTOUR returns an error. You should then 
clear bit 6. Do not use a tight loop to handle errors with bit 
6 set because that prevents other jobs from running. The 
techniques listed are for MACRO-11 and FORTRAN IV 
under the SJ and FB monitors. 


Setting Up and Using I/O Buffers 


When you transfer character strings, you normally store the 
text in buffers in your program. Input buffers do not need 
to be initialized. In MACRO-—11 programs, use .BLKB to re- 
serve space for an input buffer. In FORTRAN IV programs, 
you must use an array of data type BYTE or LOGICAL*1. 
The buffer must have enough space for the largest message 
the program expects to receive. If you overflow the buffer, 
you will corrupt your program code or data areas at run time. 

Output buffers must be initialized before you output 
any data. You can either build a message at run time by 
moving text into the buffer, or define the text of a fixed 
message at compile time. The MACRO-—11 requests .ASCII 
or .ASCIZ define text messages. .ASCIZ terminates the string 
with a byte containing binary zero (null byte). Some string 
manipulation routines in SYSLIB expect strings in the 
.ASCIZ format. 

The FORTRAN IV DATA statement defines the con- 
tents of a LOGICAL*1 array. This statement is suitable only 
for short character strings. The string manipulation rou- 
tines in SYSLIB make it easier to define strings, but the text 
has to be moved into the buffers at run time. 

To illustrate the ways to use the terminal I/O requests 
discussed so far, we have chosen some common applica- 
tions for you to study. The programs (PR1201.MAC and 
PR1201.FOR) which follow store multiple lines of input from 
the terminal. They use a null byte to terminate each line of 
text within the buffer, which means the carriage return and 
line feed characters are not stored. This saves one byte per 
line, and also means that the messages can be used in the 
SYSLIB string manipulation routines. 
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AREA: 
PROMPT: 
MSGBFR: 


- TITLE 
»-MCALL 
»-MCALL 


PR1201 
»TTYIN 
-RCTRLO 


Data Defintions 


» BLKW 
-ASCIZ 
-BLKB 
EVEN 
Program 
MoV 
»TTYOUT 
TSTB 
BNE 
mov 
MOV 
-TTYIN 
DEC 
BEG 
CMPB 
BNE 
CLRB 
-TTYIN 
TSTB 
BNE 

BR 


Buffer full. 


CLRB 
CLRB 
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-RCTRLO 
» TTINR 
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MOV 

BIC 
-POKE 
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MOV 

- TTYOUT 
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» TTYOUT 
» TTYOUT 
INC 
TSTB 
BNE 
~EXIT 

- END 


“Enter messages: 


100. 
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CR1)+ 

CR1) 

10$ 
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R2 

OFLO 
#15,R0 
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GET 
PRINT 
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RO,R1 
#100,R1 
#AREA, #44,R1 
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*MSGBFR,R1 
CR1)+ 

CR1) 

10$ 

#15 

#12 

R1 

CR1) 

10$ 


START 


-- TERMINAL I/0 EXAMPLE 
-TTYOUT .TTINR 
~-EXIT 


»-PEEK -POKE 


;EMT argument block 


;Input buffer 


;Point to prompt buffer 
sPrint Cw/wait) 1 char 
;End of message? 

;Loop if not 

;Point to input buffer 
sLoad maximum char count 
s;Read (w/wait) 1 char 
sDecrement char count 
;Branch if buffer full 
sWas char a <CR>? 
;Branch if not 

;Yes, store null byte 
3;Get <LF> char 

sWas last line blank? 
;Branch if not for more 
;Otherwise, print buffer 


Flush terminal input buffer 


;Append null bytes 

; to mark end of text 
3Get JSW 

sMove to R1 

sInhibit TT wait 
;Update JSW 

sReset Control/O 
s;Read Cwo/wait) 1 char 
;Branch if char read 
3;Get JSW 

sMove to R1 

sEnable TT wait 
;Update JSR 

sReset Control/0 
sLoad buffer address 
sPrint Cw/wait) 1 char 
;I5 next byte null? 
sBranch if not 
;Otherwise print <CR»> 
; and <LF> 

;Skip over null byte 
;Is next byte null? 
sBranch if not 
;sOtherwise, exit 
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PR1201.FOR PROGRAM PR1201 


BYTE MSGBFRC100),PROMPTC80) ! MESSAGE BUFFERS 
CALL SCOPYC’ENTER MESSAGES: ‘’,PROMPT) 


Output prompt. 


DO 10,1#1,80 

IF CPROMPTCI) .EQG@. 02 GO TO 20 

IF CITTOURCPROMPTCI)) .NE. 02 GO TOS 
CONTINUE 


Now input lines of text terminated by two <CRos. 


DO 40 [#1,100 

IERR=ITTINRC) ! ACCEPT CHAR 

IF CIERR .LT. 02 GO TO 25 ! LOOP UNTIL READ 
MSGBFRCID=IERR ! STORE CHAR IN BUFFER 
IF CMSGBFRCI) .NE. "15) GO TO 40 

MSGBFRCI)=0 ! CHANGE <CR> TO NULL 

IF CITTINRGD .LT. 029 GO TO 30 

IF CI .NE. 1 .AND. MSGBFRCI-1) .EQ@. 09 GO TO 100 
CONTINUE 


Buffer overflowed Cmore than 100 chars typed) 
Read & lose remaining chars in input buffer. 


CALL I[POKEC"44, IPEEKC"44).0R."%100) 

CALL RCTRLO ! INHIBIT TT WAIT 

IF CITTINRCD .GE. 0) GO TO 65 

CALL IPOKEC"44,IPEEKC"44) .AND. .NOT. 100) 
CALL RCTRLO ! ENABLE TT WAIT 
MSGBFRC99) =0 ! ADD 2 NULLS TO BUFFER 
MSGBFRC100)=0 


Now output messages entered. 


DO 130 1#1,100 

IF CMSGBFRCI) .NE. 02 GO TO 110 

IF CITTOURC"1S) .NE. 0) GO TO 102 ! OUTPUT <CR> 
IF CITTOURC"12) .NE. 09 GO TO 103 ! AND <LF> 
IF CMSGBFRCI+1) .EQ@. 0) GO TO 150 ! STOP IF 2 NULLS 
GO TQ 130 

IERR=ITTOURCMSGBFRCI)) |! OUTPUT A CHAR 

IF CIERR .NE. 09 GO TO 110 ! LOOP UNTIL OUTPUT 
CONTINUE 

CALL EXIT ! EXIT 

END 
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Programming with RT-—11 


As you study the MACRO-11 or FORTRAN IV pro- 
gram, look for: 


e The input process 
¢ Multiple-line buffering 
e The response if too many characters are entered 


e The procedure for printing multiple lines 


The programs do not store carriage return or line feed. 
Carriage return is stored as a null byte, and line feed is dis- 
carded. The programs contain code to clear the system’s 
terminal input buffer if the operator types in more than 100 
characters. They set bit 6 of the JSW, so that an error indi- 
cation is returned when there are no more characters in the 
buffer (all type-ahead has been cleared). They then loop, 
reading the buffer until they receive the error code. This 
indicates that the buffer is empty, and the programs clear 
bit 6 again. If they did not empty the buffer, the type-ahead 
characters would still exist, and would be read later by the 
system. KMON would then try to interpret the data as a 
monitor command. 


In this exercise you will write programs to perform terminal 
I/O. You can write the programs either in MACRO-—11 or 
FORTRAN IV, using the programmed requests discussed in 
this chapter. Write the programs so that they can be run un- 
der the FB or SJ monitor. 


1. . Write a program that prompts ““PLEASE TYPE IN 
YOUR NAME.” After the user types a name, your pro- 
gram should respond: 


WELCOME TO RT-11, USer’sS name 


Write a program that does the following: 


a. Prompts the user to input a message. The user 
should type a single line of text, terminated with a 
carriage return. 
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Loops, printing the user’s text repeatedly on the 
same line. When the output reaches column 80, 
the program should output a carriage return and 
line feed and continue the output on the next line. 
The program repeats this until the user presses 


(RETURN), (LINEFEED), Or (CTRUZ). Other characters are 
ignored. 


Repeats steps a. and b. until, during step a., the 
user types a blank line (responds to the prompt 
with (retuRN)). Then the program exits. 


Terminal Special Mode 


When using .TTYIN, .TTINR, or ITTINR, I/O data is nor- 
mally buffered until the line is terminated by (return), (LineFEED), 
(cTRUZ), OF (cTRUC). You can edit a line using (oeteTey or (cTRVU), and 
each character is echoed as typed with no special action 
performed by the user program. When the line terminator 
is received, all the characters in the buffer are passed to the 
program one at a time. 

Under terminal special mode, characters are made 
available to a program as soon as they are typed in. There 
is no delay caused by waiting for a line terminator. In this 
mode the normal (octete) and «ctru) actions are disabled. These 
characters are passed to the program, to be handled as you 
want. Terminal echo is also disabled under terminal spe- 
cial mode, except for (ctrucy and (ctrvo). If you want the input 
echoed, you must code the output commands yourself. 

Terminal special mode, which is enabled by setting bit 
12 of JSW, is used for: 


e Password entry, with echo suppressed. 


e Single-character responses to program prompts. For 
example, Yes or No type questions can be answered 
with Y or N. 
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e Single-character unechoed input. For example, pro- 
vide function keys to control the video display in the 
video editor KED. 


. Line-oriented Output 


In addition to programmed requests that perform single- 
character terminal I/O, RT—-11 supports I/O operations that 
transfer a whole line or message using a single request. For 
example, you can use the PRINT request to issue a prompt 
to the user, indicating what information is needed next. The 
PRINT request causes the contents of the specified buffer 
to be printed on the terminal. The last byte in the buffer 
must contain either 0 (NULL) or 200 (octal). 


e If NULL, the monitor adds a carriage return and line 
feed to the end of the message. 


¢ If 200 (octal), the monitor leaves the print head (or 
cursor on a display terminal) at the next character 
position after the last character printed. 


If you include a carriage return and line feed in your mes- 
sage, they are printed, making the message multiline. 


Using .PRINT in MACRO-11 


The MACRO-11 programmed request has the format: 
PRINT addr 


In this format, ‘addr’ is the address of the message buffer. 


ere veueenee einai ae eae eat ee ia 


AS REOMCTEAE NRTA Cm I IGN PERE UO PSUR OEE EEN aston nee MaaRCR EEE 


| PRINT. ans 
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MESS: .ASCII /THIS IS THE FIRST LINE OF THE MESSAGE/ 
-BYTE 15,12 
; -ASCIZ /THIS IS THE SECOND LINE OF THE MESSAGE/ 


-PRINT from a Foreground Job 


If two jobs share a terminal and the foreground job issues 
a .PRINT request, the message is printed immediately. If the 
foreground job uses .TTYOUT or ITTOUR requests, the 
message is delayed until the background job finishes typ- 
ing its current line. For this reason, you should use .PRINT 
rather than .TTYOUT or ITTOUR for critical messages from 
a foreground job. 

When a foreground job and a background job are run- 
ning, the job producing output is indicated by a B> or F> 
preceding the output. These markers are printed only when 
the job producing the output changes. When a system job 
prints a message, the logical job name is used as the 
identifier. 


Using PRINT in FORTRAN IV 
The FORTRAN IV request has the format: 


CALL PRINT (message) 


In this format, ‘‘message”’ can be a quoted string, passed as 
a single line, or an array containing characters, terminated 
with a null byte or 200 (octal). To place the value 200 (oc- 
tal) in a string, you can use the SYSLIB subroutine 
CONCAT. 


er ror segues gerne rasan gremmisiesn ane timgncimgimesig atone scccarceer rane es wntmeitatte tiga 
i 


EXAMPLE 


BYTE MESSAGC80) ‘MESSAGE ARRAY 
CALL. CONCAT €’TYPE- IN A NUMBER: *%, 200,MESSAG) 
CALL PRINT. CMESSAG) 


eterna. tie iis Si nk SME ph ENERO RSE ON DRO i EES NS NR Na ME Et Na SS RBA AEB OS A 7 RG ABS Hw ASB tsb SE AB EH 
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Line-oriented Input 


The GTLIN request inputs a complete line of text and stores 
it in the specified buffer in ASCIZ format. The maximum 
number of characters allowed for the input line is 80. You 
should, however, allocate 81 bytes to the buffer to make 
room for the trailing null byte. The GTLIN request uses the 
USR to input the line but does not check the syntax of the 
input text. The form of the MACRO-11 request is: 


.GTLIN addr 


In this format, “addr” is the address of the input buffer. The 
FORTRAN IV call is: 


CALL GTLIN(buffer) 


Here, “‘buffer’’ is an array or variable. 


nso et ts er Mr RTP RE MMe mr a eT I es REM 


EXAMPLE 


wall 


“LOGICAL*1 1OBUF(81)  !HOLDS UP TO 80 CHARACTERS 
CALE: GTCINCLOBUF 9% See ees 


g(t oe rm se ee ananance cone mrmmnreg 
Fr g 


E 5 
Bicdatand hula dana Walid ata th ata 


SAE iat aoa SOR NSS TR eens Sta BS a Wo A Neha a NR i echadlendtia nena 


GTLIN has another form, which allows you to print a 
prompt on the terminal before reading the input line. The 
MACRO-11 request for this is: 


.GTLIN — baddr,paddr 


In this request, ‘‘baddr’’ is the address of the input buffer, 
and ‘“‘paddr’”’ is the address of the prompt buffer. The FOR- 
TRAN IV cail is: 


CALL GTLIN(BUFFER,PROMPT) 


Each argument is an array or variable. 

The GTLIN prompt string has the same format as the 
PRINT output string. A null byte at the end of the string 
causes a Carriage return and line feed to be printed after the 
prompt. The value 200 (octal) at the end of the string leaves 
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the print head (or cursor) on the same line. Prompts usu- 
ally end with 200 (octal), so that the input is on the same 
line as the prompt. 

GTLIN converts lowercase letters to uppercase, unless 
bit 14 of the JSW is set. This bit controls lowercase to up- 
percase conversion for terminal input requests. 


Input from Indirect Command Files 


The GTLIN request accepts data from an indirect command 
file if one is active. Otherwise, input is from the terminal. 
The .TTYIN requests can accept input from the terminal 
only. Thus, you should use the .TTYIN requests if you want 
to make sure that data arrives from the terminal. 

If you use .GTLIN for input, and the program is run 
from an indirect command file, the input data must be taken 
into consideration as the command file is created. Lines of 
data can be included in the command file, to be read by the 
.GTLIN requests in the program. Sometimes you may want 
to switch the input data stream from the command file to 
the terminal. For example, to read a quantity of known data,. 
which can be entered in a command file, and then ask the 
user to type in responses on-line, you must indicate in the 
program data that you want to switch the input to the ter- 
minal. 


1. Set bit 3 of the job status word. This enables the in- 
put stream to be switched when requested. It does 
not switch the stream automatically. 


2. Insert the characters ~C (a circumflex followed by a 
C) in the command file at the point where you want 
to enable data input from the terminal. 


Normally, a job using .GTLIN to read data treats *C in 
an indirect command file as if it were the ctruc) character, 
and the job is aborted. But if bit 3 of the JSW is set, all fur- 
ther input for the job comes from the terminal. You cannot 
switch the input data stream back to the command file un- 
til the job terminates. If you clear bit 3 from the program, 
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the next .GTLIN request aborts the job, as if (ctruc) had been 
typed. 

If the monitor command SET TT NOQUIET is in ef- 
fect, data read by .GTLIN from a command file is echoed 
on the terminal. If SET TT QUIET is specified, no echoing 
is performed. 


Handling (CTRL) 


(cruc) is the normal way for you to return control to the RT— 
11 monitor from a program. Pressing ctrucy once aborts the 
program the next time it requests terminal input, and 
pressing (ctruc) twice aborts the program immediately. 

You can disable cctruc) to prevent the user from abort- 
ing your program, but you should do so only for thor- 
oughly debugged code. If you disable ctruc) and the pro- 
gram goes into an infinite loop, the only way to stop it is 
to reboot the system. When cctruc) is disabled, any single 
(cTRUC) passes as an ASCII character (octal value 3). You dis- 
able ctruc) using the .SCCA request as follows: 


.SCCA area, flagaddr (MACRO-11) 
CALL SCCA (FLAG) (FORTRAN IV) 


In MACRO-—11, ‘‘area”’ is the address of a two-word param- 
eter block, and ‘‘flagaddr’”’ is the address of a terminal sta- 
tus word (flag word). In FORTRAN IV “FLAG” is an inte- 
ger variable to be used as the flag word. 

If (ctruc) is pressed twice, RMON sets bit 15 of the flag 
word. If you want to detect another double (ctruc), your pro- 
gram must clear this bit. To reset to normal (ctruc) action, 
use: 


.SCCA area, #0 (MACRO-11) 
CALL SCCA (FORTRAN IV) 


Handling (CTRU/O) 


(ctrvo) inhibits output to the console terminal until another 
(cro) is received, or until the program resets the ctruo) switch. 


Practice 
12-—2 
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The program continues to be executed, but RMON does not 
perform terminal output requests while (ctruo) is in effect. 
All the output requests terminate successfully immedi- 
ately, and the program executes much faster than if it had 
to wait for I/O completion. 

(crv0) is most useful when you want to examine a small 
part of a long text file. You can suppress the output of sec- 
tions that you do not need to see. In this way you can scan 
the file very rapidly. 

When writing a program, you may want to be sure that 
data is printed on the console terminal. You can use the 
RCTRLO request to reset (ctrvo) if it is in effect. 


EXAMPLE 

The MACRO-11 form of this request is: 
-RCTRLO ;Reset (CTRU/O) | 

The FORTRAN IV form is: 


CALL RCTRLO 


Bocrascwsninstaonnasvib eet edna ttc n hatin sane dd ia la MECN canner tetinanbndannn mura onMnt tinct tel: ntedniiuioilae idan mess SentiaNLaNRMAcLeRU MAE OIL AONB 


When this request is called, printing on the console termi- 
nal is enabled regardless of the status of (ctruo). It is recom- 
mended that you issue a .RCTRLO or RCTRLO request after 
setting or clearing any bits in the JSW. 


Modify the second program you wrote for practice 12—1 so 
that it uses the .GTLIN or GTLIN request to accept the ini- 
tial input. : 


Use .PRINT or PRINT to output the text. Print each output 

message on a separate line. Continue until the user presses 
(RETURN), (LINEFEED), OF (CTRUZ), then reset (cTRUO) and repeat the in- 
put prompt. 
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Using 
Multiterminal 
Input/Output 


RT-—11 provides support for 1 to 16 additional terminals. 
You can select multiterminal support at system generation 
time. It is available for the SJ, FB, and XM monitors. 

RT-11 provides special programmed requests for 
multiterminal I/O. The input and output requests are sim- 
ilar to the terminal I/O requests discussed in chapter 12, 
“Using Terminal Input/Output.” There are additional mul- 
titerminal requests to attach, detach, obtain, and set status 
information about specific terminals. 

This chapter describes the features provided by the 
multiterminal support option and the possible hardware 
configurations. You will learn the significance of the sys- 
tem console in a multiterminal system, as well as how to 
change the system console, how to run foreground and sys- 
tem jobs with specific terminals as their consoles, and how 
to write programs for multiterminal applications. 
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Multiterminal Support 


RT—11 provides support for up to 16 additional terminals 
through a feature which can be selected during system gen- 
eration. The multiterminal option is available for all three 
monitors. Multiple-terminal support does not provide a 
multiuser system, because RT—11 supports only one ter- 
minal at a time as the system console. You can transfer the 
system console from the initial terminal to any of the local 
terminals. The extra terminals are only I/O devices con- 
trolled by applications programs. 


Hardware Configuration 


The multiple-terminal feature supports terminals con- 
nected through DL11 and DZ11 serial line interfaces (DLV11 
and DZV11 for an LSJ—11). The terminals connected to these 
interfaces can be either local or remote. A local terminal is 
connected directly to the DL or DZ interface. A remote ter- 
minal is connected to the DL or DZ interface by a modem 
and a communication link. Figure 39 shows a local termi- 
nal and a remote terminal connected to a DL11 ora DZ11. 
During system generation, you must specify which termi- 
nals are local and which are remote. 


The System Console 


The system or background console is the terminal used to 
enter monitor commands and communicate with the back- 
ground job. KMON prompts you on this terminal, and the 
terminal I/O programmed requests (discussed in chapter 12, 
“Using Terminal Input/Output”) communicate with this 
terminal from background jobs. By default, the terminal I/O 
requests from foreground and system jobs also use this ter- 
minal. 

When running a foreground or system job, you can use 
the /TERMINAL option with the FRUN or SRUN command 
to assign a terminal for the exclusive use of the job (see 
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Figure 39. 
Local and Remote Terminal Connections 


LOCAL 
TERMINAL 


COMMUNICATIONS 
LINK 


REMOTE 
TERMINAL 


chapter 2, “Executing Programs’’). Such a terminal cannot 
be shared by another job. When you assign a terminal to a 
job, you must use that terminal to enter data to the job and 
to abort the job with (crrauc) (ctrucy. You cannot communicate 
with the job by using <ctrury or (ctrux) on the system console. 
You can terminate a foreground or system job that has an 
assigned terminal, by issuing the ABORT command at the 
system console. 

You can move the system console to any local termi- 
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nal connected to your system (except a terminal assigned 
to a foreground or system job) by using the command: 


SET TERM CONSOL=n 


Here nh” is the logical unit number of the new console ter- 
minal. After you press (return) to terminate this command, 
RT-11 prints its next prompt on the new system console. 

RT—11 does not allow you to set a remote terminal as 
the system console. A patch to enable you to use a remote 
terminal as the system console is given in appendix D of 
the RT—11 System Generation Guide. 


Multiterminal Programming 


An application program can communicate with up to 16 
terminals, in addition to the system console, by using the 
multiterminal programmed requests listed in table 14. 
If you assign a terminal using FRUN/TERMINAL or 
SRUN/TERMINAL, you do not need multiterminal requests 
to communicate with that terminal. 


Table 14. 
Multiterminal Programmed Requests 
MACRO-11 FORTRAN IV 
Request Request Function 

_ .MTATCH MTATCH Attach a terminal 
.MTIN MTIN Input character(s) 
.MTOUT MTOUT Output character(s) 
-.MTPRNT MTPRNT Output a character string 
.MTRCTO MTRCTO Reset (ctrvo) 
-.MTSTAT MTSTAT Get multiterminal system status 
.MTGET MTGET Get terminal status 
.MTSET MTSET Set terminal status 
.MTDTCH MTDTCH Detach a terminal 
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The input and output requests are similar to the con- 
sole terminal I/O requests .TTYIN, .TTYOUT, and .PRINT. 
Before you can communicate with a terminal using these 
requests, you must reserve that terminal, using the 
-MTATCH or MTATCH request. When you have finished 
using a terminal, you must release it, using the .MTDTCH 
or MTDTCH request. 


Terminal Control Blocks 


When you request multiple-terminal support during sys- 
tem generation, the SYSGEN procedure creates a terminal 
control block (TCB) for each terminal you specify. The TCBs 
are assigned to the terminals, starting with the hardware 
console, and continuing in the following order: 


1. Local DLs 
2. Remote DLs 
3. Local DZs 
4. Remote DZs 


The number of the TCB assigned to a terminal be- 
comes the logical unit number (LUN) of that terminal, with 
the hardware console having LUN 0. The TCBs are linked 
into RMON and form a contiguous table. The .MTSTAT or 
MTSTAT request returns information that enables you to 
access the TCBs directly, using the .GVAL request. The 
programmed requests .MTGET and MTGET retrieve infor- 
mation from the TCB. The requests .MTSET and MTSET 
allow you to change this information. 

The first word in the TCB is the terminal configuration 
word, shown in figure 40. Bits 6, 12, and 14 of this word 
have a similar effect to the corresponding bits in the JSW, 
that is: 


e Bit 6 is the inhibit wait bit. If this bit is set, the pro- 
gram does not wait for I/O to complete. 
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Figure 40. 
TCB Configuration Word 


T.CNFG ~ 
Th 980-92 14 08 07 O06 05. 04 03 02 01 


Pele ewes iola 
USED 


TAB IN EFFECT 
CRLF IN EFFECT 


ierecen” FORM FEED 
IN EFFECT 


CTRL/F/B/X IN EFFECT 
INHIBIT WAIT ON INPUT 
XON/XOFF 

BAUD RATE MASK (DZ11) 
SPECIAL MODE INPUT 
REMOTE TERMINAL 
LOWERCASE ENABLED 
SET TT SCOPE IN EFFECT 


¢ Bit 12 is the special mode bit. If this bit is set, input 
is in special mode, characters are not echoed, and so 
on. 


¢ Bit 14 is the lowercase bit. If this bit is clear, all 
characters are converted to uppercase. If this bit is 
set, lowercase characters are passed. 


In multiterminal applications, you can set these bits for the 
system console either in the JSW or in the TCB. Setting the 
bits in either place results in both words having those bits 
set. 


Programming Multiterminal I/O 


The sequence of events and requests which you should use 
when programming multiterminal applications is given 
below: 


1. Examine the system status. To determine if the sys- 
tem under which the job is running has multiter- 
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minal support, check the SYSGEN features word 
(RMON fixed offset 372). 


2. Attach a terminal. A job must attach a terminal be- 
fore it can communicate with that terminal by means 
of the multiterminal I/O requests. Use the request 
-MTATCH or MTATCH, and specify the logical unit 
number of the terminal to be attached. 


Once a job has attached a terminal, no other job can 
attach or communicate with it until the job issues a 
-.MTDTCH request or terminates. 


As an optional argument, you can specify the address 
of an asynchronous terminal status word. If you spec- 
ify this argument, the system automatically notifies 
your job of certain changes in the terminal’s status. 
This word is described later. 


3. Initialize the terminal characteristics. Use the 
.MTGET or MTGET request to obtain complete status 
information about the terminal you have attached. 
The status block returned by this request contains the 
first six bytes of the TCB, including the terminal con- 
figuration word (figure 40). Byte 7 is the terminal 
state byte, shown in figure 41. Byte 8 is the carriage 
width, indicating the maximum number of characters 
on a line. 


Figure 41. 
Terminal State Byte 


165 14 13 12 #11 =+#10 O9 00 


TERMINAL IS SHARED CONSOLE 


TERMINAL IS HUNG UP 
DZ11 INTERFACE 
DOUBLE CTRL/C ENTERED 


TERMINAL IS A CONSOLE 
(LOCAL DL11 ONLY) 
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To change any of the characteristics, you must 
modify the data in the status block received by 
-MTGET or MTGET, and return the new values using 
the .MTSET or MTSET request. 


You can get status information about terminals that 
are not attached to your job; however, you can set 
characteristics for attached terminals only. 


4. Communicate with the terminal. A job can get 
characters from an attached terminal using the 
.MTIN or MTIN request. This is equivalent to the 
-TTYIN or ITTINR request, except that you can spec- 
ify the number of characters to be received. 


A job outputs characters using the .MTOUT or 
MTOUT request, and character strings, using the 
-.MTPRNT request. These are equivalent to the 
-TTYOUT or ITTOUT and .PRINT or PRINT requests. 


If you want to enable asynchronous I/O, special mode 
V/O, or lowercase I/O, first set the appropriate bits in 
the terminal configuration word using .MTSET or 
MTSET. 


Use the .MTRCTO or MTRCTO request to reset the 
effect of a (ctruo). This is equivalent to the .RCTRLO or 
RCTRLO request. 

You should issue a .MTRCTO or MTRCTO request 
after setting or clearing any bits in the job’s JSW or 
any TCB, and before issuing the first terminal I/O re- 
quest. This forces the monitor to update all the termi- 
nal data structures with the new status. 


5. Release the terminal. When the job has finished, it 
should detach the terminal to make it available for 
use by other jobs. Use the .MTDTCH or MTDTCH 
request. 


Debugging a Multiterminal Application 


Use VDT, the virtual debugging technique, to debug a mul- 
titerminal application program. 
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Figure 42. 
Asynchronous Terminal Status Word 


15 14 13 12 08 O07 O6 O5 


: 00 
eae RESERVED Eo RESERVED 


AS.HNG TERMINAL HAS HUNG 


AS.CAR CARRIER PRESENT 

AS.OUT OUTPUT RING BUFFER 
IS EMPTY 

AS.INP INPUT IS AVAILABLE 


AS.CTC DOUBLE CTRL/C WAS 
TYPED 


Asynchronous Terminal Status 


Practice 
13-—1 


If you select the asynchronous terminal status feature dur- 
ing system generation, the multiterminal interrupt service 
code automatically notifies a job of certain changes in ter- 
minal status after it has been attached. An optional argu- 
ment to the .MTATCH or MTATCH request specifies the 
location to be used as the asynchronous terminal status 
word. Without this feature, a job must issue a .MTGET or 
MTGET request to detect any changes in status. Figure 42 
shows the format of the asynchronous terminal status word. 


You may write the following multiterminal program in 
either MACRO-11 or FORTRAN IV, to run under the moni- 
tor you prefer. The program should: 


1. Check whether or not the system has multiterminal 
support. If not, it should print an error message on the 
console and exit. 


Attach one of the available terminals, other than the 
system console. 


Enable lowercase I/O at that terminal. 
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Display (on that terminal) a prompt asking for the 
user’s name, for example: 


Who are you? 


Read the user’s name and then display a response like: 


Welcome to Multiterminal RT-11, Ann 


Release the terminal and exit. 


References 
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Chapter 11, “Using Input/Output Systems,” discussed briefly 
the basic types of I/O available: terminal I/O, queued I/O, 
and OTS J/O. 

The mode of I/O operation presented in this chapter 
is called synchronous because program execution is sus- 
pended until the requested I/O is completed. Asynchro- 
nous I/O and event-driven I/O, on the other hand, return 
control to the program before the transfer is. completed. 
These two I/O modes are discussed in chapter 15, ‘Using 
Nonsynchronous Queued Input/Output.” 

The MACRO-11 programmed requests described in this 
chapter include: .READW, .WRITW, .FETCH, .ENTER/ 
_.LOOKUP, .CLOSE/.PURGE, .RELEAS, .CDFN, .QSET, and 
.DSTATUS. The FORTRAN IV requests covered include: 
IREADW, IWRITW, IFETCH/IGETC, IENTER/LOOKUP, 
CLOSEC/PURGE, IFREEC, ICDFN, IQSET, and IDSTAT. 

When you have completed this chapter, you will be 
able to use synchronous queued I/O requests to read data 
stored in a file, create a new file and use synchronous 
queued I/O requests to write data to it, and use synchro- 
nous queued I/O requests to read data from or write data 
to a non-file-structured device. 
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Concepts of Queued I/O 


The RT—11 queued I/O system is used for most I/O to sup- 
ported I/O devices, including I/O to file-structured and non- 
file-structured devices. Queued I/O allows device-indepen- 
dent programming and is implemented using the following 
software components: 


¢ RMON, which receives the programmed requests gov- 
erning queued J/O operations and passes them on to 
other components. RMON also keeps track of I/O 
activity. 


e USR, which connects jobs to peripheral devices and 
handles all access to file directories on volumes. 


e Device handlers, which are software routines con- 
taining code to handle the details of device specific 
I/O operations. 


Queued I/O is the method used by RT—11 to keep track 
of pending I/O operations. The choice of the next I/O op- 
eration to be performed by the operating system is made by 
looking at a list, or queue, of requests. Each I/O request re- 
sults in RMON passing a data structure called a ‘‘queue 
element” to the device handler. The queue element con- 
tains all the information needed by the device handler to 
perform the requested operation. 


_ Using I/O Channels 


Although there may be almost any number of devices and 
files in a given RT—11 system, a specific program uses only 
a limited number at any given time. Access to devices and 
files is controlled through a set of I/O “channels.” Once a 
channel is open to a device or a file, the program may call 
for I/O to be performed to the device or file to which the 
channel is connected. 
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Standard Sequence of Requests 


The following programs (PR1401.MAC and PRO1402.FOR) 
show how queued I/O requests are performed. The pro- 
gram must perform a basic sequence of activities if suc- 
cessful queued I/O is to occur. These activities are: 


1. Make sure that the device handler is in memory. 
2. Open a channel to the file or device. 

3. Read from and/or write to the channel. 

4. Close the channel after all I/O has been completed. 
5. Release the device handler from memory. 


Performing Queued I/O 


Before any queued. I/O operations can be performed on a 
device, the device handler must be resident in memory. The 
device handler can be loaded either by the console LOAD 
command or by the program through a programmed 
request. 


Fetching Device Handlers 


The MACRO-11 programmed request to load a device han- 
dler is .FETCH. The FORTRAN IV system subroutine is 
IFETCH. These requests bring the specified handler into 
memory. The form of the MACRO-11 .FETCH pro- 
grammed request is: 


FETCH  addr,devnam 


In this request, ‘‘addr’’ is the address at which the handler 
is to be loaded, and ‘‘devnam’’ is the address of a RAD50 
word containing the device name. 
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EMTARG: 
INFILE: 
OUTFIL: 
LIMITS: 
BUFFER: 
ERROR: 

ANNCE: 

FCH1IMS: 
FCHeMS: 
LKPMES: 
ENTMES: 
RERRMS: 
WERRMS: 


LKPERR: 


FCH2ER: 


FCHIER: 
ERDONE: 


-TITLE COPY1 1/0 EXAMPLE PROGRAM 


Program copies one file to another and exits. 


.MCALL .EXIT. 
.MCALL .READW 


- FETCH 
-WRITW 


-LOOKUP .ENTER 
-CLOSE .SRESET 
-BLKW 6 ;EMT argument block 
»RADSO /DK TRAN1 XYZ/ ;Copy from DK: TRAN1.XYZ 
-RADSO /DK TRAN2 XYZ/ ; to DK: TRAN2.XYZ 

»LIMIT ;Generate program limits 
» BLKW sFile I/O Buffer 

- BYTE ;Error status byte 
-ASCIZ “Program copies TRAN1.XYZ to TRAN2.XY2" 
-ASCIZ “Error on FETCH of output handler" 
-ASCIZ “Error on FETCH of input handler" 

-ASCIZ “Error on LOOKUP of input file” 

-ASCIZ “Error on creation of output file™ 
-ASCIZ “Read error, copy aborted" 

-ASCIZ "Write error, copy aborted" 

-ASCIZ “Protected output file already exists" 
«EVEN 
-SBTTL 


-PRINT 


256. 


SETUP -- Setup Files For Copy 

This routine sets up files for I/O. 

File specifications are fixed in this version. 
Routine returns with C-Bit SET on error. 


MOV R1,-(CSP) 
-PRINT #ANNCE 

Fetch device handlers 
MOV LIMITS+2,Ri 
-FETCH R1,#OUTFIL 
BCS FCH1IER 

MOV RO,R1 


;Save register 
;Announce program 


;Load free memory address 
;Get output device handler 
sBranch on FETCH error 
;Copy free address 

-FETCH R1,#INFILE 3Get input device handler 
BCS FCH2ER sBranch on FETCH error 
Open input and output files 

«LOOKUP #EMTARG,#3,#INFILE ;Open input file 

Bcs LKPERR s;Branch if failed 

MOV RO,R1 ;Save input file length 
-ENTER #EMTARG,#0,#OUTFIL ;Create output file 

BCC DONE ;Return if no error 

Error Routines 

-PRINT #ENTMES ;Issue error creating output 
BR ERDONE ; file message and return 
-PRINT #LKPMES ;Issue failed to open input 
BR ERDONE ; file message and return 
»-PRINT #FCH2MS ;Issue FETCH error message 
BR ERDONE 3; and return 

-PRINT #FCH1MS ;Issue FETCH error message 
SEC sIndicate error occurred 


PR1401.MAC 
(continued) 
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RDERR: 
WERR: 


EREXIT: 
EXIT: 


1$; 


CLSCHN: 


PRGCHN: 
RESET: 


MOV CSP)+,R1 ;Restore R1 Csave C-bit) 
RETURN sReturn to caller 
-SBTTL CPYRTN -- Synchronous Copy (Single Buffer) 


Routine assumes that the input file is opened 
on channel 3 and the output on channel 0. 
Returns with C-BIT SET on error. 


Note: All registers except RO are preserved. 


MOV R1,-CSP) ;Save register 

CLR R1 ;Clear block number 

CLRB ERROR ;Init error flag 

-READW #EMTARG, #3, BUFFER, #256. ,R1 

BCC es ;Branch if read succeeded 
TSTB af#S2 sEnd-Of-File reached? 

BEQ EXIT ;Branch if so 

BR RDERR ;Otherwise, process error 
-WRITW #EMTARG, #0,#BUFFER, #256. ,R1 

BCS WERR ;Branch on write failure 
INC R1 ;Update block number 

BR 1$ sAnd read next block 
«PRINT #RERRMS ;Issue read error message 
BR EREXIT ;And finish up 

-PRINT #WERRMS ;Issue write error message 
DECB ERROR ;Set error flag 

MOV CSP)+,R1 ;Restore saved register 


TSTB ERROR sError? Cand clear C-BIT) 


BEQ 1$ sBranch if not 

SEC s;Otherwise, set C-BIT 

RETURN sReturn to caller 

-SBTTL CLSCHN -- Cleanup For Copy Program 

-CLOSE #3 ;Close input file 

-CLOSE #0 ;Close output file 

BCC RESET ;Branch if succeeded 

-PRINT #PRICT ;Output file is protected 
;Purge files €.SRESET) 

-SRESET ;Reset system 

RETURN sReturn to caller 

-SBTTL MAIN PROGRAM 

CALL SETUP 3;Get file names 

BCS 1$ ;Branch if failed 

CALL CPYRTN ;Copy the input to output 

BCS 1$ ;Branch if failed 

CALL CLSCHN sClose the channels 

BR 2$ 

CALL PRGCHN ;Purge the channels 

-EXIT sExit 

~END START 
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PR1402.FOR PROGRAM COPY1 


Program performs a file to file copy and then 
exits. 


LOGICAL*1 SETUP,CPYRTN ! Declare functions 
LOGICAL*1 ERROR 


ERROR = SETUPC) Open files 

IF CERROR) GO TO 20 Stop on error 

ERROR = CPYRTNC) Copy file 

IF CERROR) GO TO 20 Stop on error 

CALL CLSCHN ! Close files and exit 
GO TO 30 

CALL PRGCHN ! Purge channels 

CALL EXIT 

END 

FUNCTION SETUP 


This routine sets up the files for I/0. 
File specifications are fixed in this version. 


Function returns .TRUE. if an error occurred. 
LOGICAL*1 SETUP 

INTEGER*2 INCHN,QUTCHN 

COMMON /CHNNLS/ INCHN,OUTCHN 


Channel numbers are common because they are 
used by CPYRTN, CLSCHN, and PRGCHN. 


Input CDK: TRAN1.XYZ) and output CDK: TRAN2. XYZ) 
file specifications: . 


INTEGER*2 INFILEC4),OUTFILC4) 
DATA INFILE/2RDK,3RTRA,2RN1,3RXY2/ 
DATA OUTFIL/2RDK,3RTRA, 2RN2,3RXYZ/ 


Output introductory message and allocate channels. 
CALL PRINTC’Program copies TRAN1.XYZ to TRAN2.XYZ%) 
INCHN = IGETCC) 

OUTCHN = IGETCC) 


Fetch needed device handlers. 


IF CIFETCHCOUTFILC1)) .NE. 0) GO TO 101 
IF CEFETCHCINFILEC1)) .NE. 02 GO TO 102 


Open input file. 
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PR1402.FOR LENGTH = LOQOKUPCINCHN, INFILE) 
(continued) IF CLENGTH .LT. 0) GO TO 103 


Create output file. 


IF CIENTERCOUTCHN,OUTFIL,LENGTH) .LT. 02 GO TO 104 
SETUP = .FALSE. ! No error 
‘RETURN 


ERROR ROUTINES 


CALL PRINTC’Error on FETCH of output handler’) 
GO TO 200 

CALL PRINTC’Error on FETCH of input handler’) 

GO TO 200 

CALL PRINTC’Error on LOOKUP of input file’) 

GO TO 200 

CALL PRINTC’Error on creation of output file’) 
SETUP = .TRUE. ! Error 

RETURN 

_END 

FUNCTION CPYRTN 


Single buffered, synchronous copy routine. 
Function returns .TRUE. on error. 


LOGICAL*1 CPYRTN 

INTEGER*2 INCHN,OUTCHN 

COMMON /CHNNLS/ INCHN,QOUTCHN 

INTEGER*2 BUFFERC256) , BLOCK 

BLOCK = 0 ! Init block number 


Read/write loop. 


IERR = ITREADWC256, BUFFER, BLOCK, INCHN) 

IF CIERR .GE. 0) GO TO 30 ! Read successful 
IF CIERR .EQ@. €-1)) GO TO 150 ! End of File? 
GO TO 100 ! Error 


Write out buffer just read. 

IF CIWRITWC256,BUFFER,BLOCK,QUTCHN) .LT. 0) 
GO TO 101 

BLOCK = BLOCK+1 ! Update to block 

GO TO 20 ! Read next block 

ERROR ROUTINES 


CALL PRINTC’Read error, copy aborted’) 
GO TO 140 
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(continued) 
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101 
140 


Q 


iv) 


CALL PRINTC’Write error, copy aborted’) 
CPYRTN = .TRUE. 
RETURN 


Successful return. 


CPYRTN = .FALSE. 
RETURN 

END 

SUBROUTINE CLSCHN 


Close files. 


INTEGER*2 INCHN,OUTCHN 

COMMON /CHNNLS/ INCHN,QUTCHN 

CALL CLOSECCINCHN)D 

IF CICLOSECOUTCHND .EQ@. 4) CALL PRINT 
C’Protected output file already exists’) 

RETURN 

END 

SUBROUTINE PRGCHN 


Purge channels. 


INTEGER*2 INCHN,OUTCHN 
COMMON /CHNNLS/ INCHN,QUTCHN 
CALL PURGECINCHN) 

CALL PURGECOUTCHN) 

RETURN 

END 
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The best place to put a device handler is immediately 
above the memory your program is using—the job’s high 
limit. You can keep track of the program’s high limit by us- 
ing the macro directive .LIMIT. 


' sp ae ap aaa 
EXAMPLE 

| .FETCH LIMIT+2,#LPNAM 

BCS ERROR 

| MOV RO,LIMIT+2 

| LPNAM: .RADSO /LP/ 

be CIM Te SUIMty 
| 
anc ae ine a a ca cna Ls acetamide tas a nancies aa casei aensaee 


When fetching multiple device handlers, fetch the next 
one into the area directly above the preceding one. This is 
easy because after each .FETCH, RO points to the word above 
the device handler that was last fetched. By copying RO into 
another location, you can refer to that value in implement- 
ing the next fetch. Do not do your next fetch using RO as 
the addr argument to the .FETCH macro because the con- 
tents of RO are changed in the macro expansion before it is 
referenced. 

In FORTRAN IV programs you would use the IFETCH 
routine, which has the form: 


IERR=IFETCH(devnam) 


In this routine, ‘““devnam”’ is a variable that contains the 
RAD50 code for the device handler to be fetched. The de- 
vice handler is positioned within the FORTRAN IV OTS 
workspace. 


opine cmt a nets Sg os Ret IRN ES panes Nene bathe IN ft ela ant AN NO Mona LI 


EXAMPLE _ 


INTEGER HVAR 
| DATA HVAR/3RDK / 
| TERR=IFETCHCHVAR) 


ae ell ak usenet innate 


Sir Schoen lta Scinondl mt tt at a rac lta Tannen aati at iti tana ont 2 SN aa LE CRSD BOT Reopen ENN EE Rh iS Cb CRN is BELEN 
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Selecting a Channel 


After you have fetched the device handler into memory, you 
can open I/O channels to the device. Channels are referred 
to by number. By default, channel numbers 0 to 15 (deci- 
mal), or 0 to 17 (octal), are available. If your program is not 


-overlaid, you can use any of these numbers. If it is over- 


laid, do not use channel 15 (octal 17), as this is the channel 
used by the overlay process. If necessary, you can write code 
to check bit 9 of the JSW to see if the program is overlaid. 
If a FORTRAN IV program does not use the FORTRAN 
IV OTS I/O routines, the rules above apply without change. 
If the program does use these facilities, it is up to you to 
make sure that the channel numbers you select are not being 
used for OTS I/O. OTS routines use RT—11 programmed re- 
quests to perform FORTRAN IV I/O, so some channels may 
be occupied when you try to gain access to them. To get a 
channel for your own purpose, use the IGETC request. 


verti reef Meee eee TROND AL IEP ERNRERN SOU Te I ee NE MRT erteeeresen seme AO aa RENT 


EXAMPLE 


“rcHAN= IGETCO) 


roms 


ee 


i SAN i a eS it nr ni atta as nn bc AN en hs mtn oi omic naan tales nsanMStcbnt cabs Niue aRi oe cinae 


This call asks the OTS to supply you with an available 
channel and mark the channel “‘in use” so that the OTS does 
not try to use the channel itself. IGETC returns the number 
of the channel. When your program stops using a channel, 
you must return the channel to the OTS by calling the 
IFREEC routine. 


een ea Pe TMC Ae IE ST 


EXAMPLE 


ae trceocicwen 


pec MUS 


Remember, you have not disconnected a channel until you 
have closed it by using the CLOSEC routine (discussed later). 
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Opening a Channel 


Having selected a channel, you can connect it to a device 
or to a file on a file-structured device. To connect the chan- 
nel, issue either a LOOKUP or an ENTER request. Both take 
a channel number and the address of a four-word block 
containing the device name, file name, and file type of the 
file in RAD50 format. LOOKUP connects the channel to an 
old file. ENTER connects the channel to a new file. 

If the device to which you are connecting the channel 
is not file structured, the file name and file type are ignored 
by the request and can be left zero. For a file-structured de- 
vice, the LOOKUP request searches the directory for the 
specified file; the ENTER request creates a new file with the 
name given. If the device is file structured and you perform 
a LOOKUP without specifying a file name, RT-11 opens the 
device as one large file. This is called a non-file-structured 
LOOKUP. An ENTER request to a file-structured device re- 
quires a specific file name. 

When you create a new file using ENTER, it is referred 
to as tentative. The characteristics of the tentative status are 
as follows: 


¢ The status of the directory entry for the file is flagged 
as tentative. (When the file is closed correctly, its sta- 
tus is flagged as permanent.) 


¢ A tentative length is recorded in the directory. It may 
be that not all the allocated space is used by the op- 
erations performed during the program run, but the 
allocated space is reserved for possible use by the file 
until the channel is closed. 


When the file is closed correctly, the following events take 
place: 


e The tentative status changes to permanent. 


¢ The length of the file is updated to record only the 
actual space used. The USR uses the fourth word of 
the channel table to store this information. 
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¢« Any other file on the same volume with the same 
name and file type is deleted. 


In general, when you use ENTER to create a file which 
has the same specification as an old file, the old file is de- 
leted when the new one is closed. This does not occur, 
however, if the old file is protected. You can prevent an 
unprotected file from being deleted by accident. Before is- 
suing an ENTER request, perform a LOOKUP operation to 
see if there is a file with that name. If the LOOKUP opera- 
tion fails because the file is not found, it is safe to perform 
an ENTER. A protected file is never deleted because of an 
ENTER. If you issue an ENTER request using a name as- 
signed to a protected file, the ENTER request returns an 
error. 

It may happen that when you try to close a tentative 
file, the USR finds a protected file that was not there when 
the ENTER request was issued. If this situation occurs, the 
CLOSE request returns an error but the file is closed cor- 
rectly. Then there are two files with the same name on the 
device. 

The ENTER request has one argument that the LOOKUP 
request does not have—the length you want to allocate to 
the file. The length is one of the following values: 


¢ A positive number giving the length of the file in 
blocks. The USR finds the first empty area on the de- 
vice that is large enough and allocates the specified 
number of blocks to the tentative file. 


* The value —1. The USR allocates the largest empty 
area available on the volume. 


¢ The value 0. The USR allocates the larger of either: 
half of the largest empty space or all of the second 
largest space. 


The form of the MACRO—11 request .ENTER is: 


-ENTER = area,chan,file,length 
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EXAMPLE 


-ENTER #AREA,#0,#FNAM, #0 


AREA: -BLKW 4 | 
FNAM: -RADSO /DK FILE TYP/ | 


$ 


The form of the FORTRAN IV request IENTER is: 


length = IENTER (chan, file,length) 


EXAMPLE 


LEN=IENTERCICHAN,FNAME ,LENGTH) 


The LOOKUP request is used to access a permanent 
file on the device. The MACRO-—11 request for lookup has 
the form: 


.LOOKUP _ area,chan,filename 


FORTRAN IV programmers use the LOOKUP system sub- 
routine which has the form: 


length = LOOKUP{(chan, filename) 


The LOOKUP and ENTER requests, in either 
MACRO-11 or FORTRAN IV, both return the actual num- 
ber of blocks allocated to the file. The value is returned in 
RO for MACRO-11. 


Synchronous I/O Requests 


While synchronous I/O is being performed, control does not 
return to the job that issued the request until the I/O oper- 
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ation is complete. Other jobs can be executed while the job 
is waiting for a return of control. 

To perform synchronous I/O you use the READW and 
WRITW requests. The arguments to these requests are: 


channel number Any channel referred to in the re- 
quests must have previously been 
opened using ENTER or LOOKUP. 


buffer The memory buffer is the source of 
data for a write operation, or the desti- 
nation of data for a read operation. 


word count The number of words to be transferred 
(use null bytes if necessary to fill 
words). 

block number In file I/O, the relative block number 


within the file at which the data trans- 
fer is to start.. The first block in the file 
is always block zero. 


In non-file-structured I/O to a file- 
structured device, the block number 
refers to the physical block on the de- 
vice, starting with-block 0. 


The READW and WRITW requests cause data to be read 
from and written to the device. The W means ‘wait for 
completion.’’ For MACRO-11 programmers, the form of 
these requests is: 


-READW/.WRITW _ area,channel,buffer,wordcnt,block 


For FORTRAN IV programmers, the system subrou- 
tines are called with the form: 


IERR = IREADW/IWRITW(went,buff,block,chan) 
When a job issues a synchronous J/O request, a spe- 


cific sequence of events is initiated. Refer to figure 43 while 
reading the following description of this sequence. 
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Figure 43. 
Flow of Control in Synchronous Input/Output 
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1. Using the arguments provided by the request, RMON 
builds an I/O queue element and passes it to the ap- 
propriate device handler. 


2. The device handler starts the I/O operation and re- 
turns control to RMON. 


3. RMON blocks the job that issued the request, and 
starts a scheduling search that results in control 
being passed to any lower priority jobs waiting to 
run. 


4. The I/O is controlled either by direct memory access 
(DMA) or interrupt processing, while other jobs, if 
any, execute. DMA is a mode of memory access by 
which a device can access memory locations directly 
with no help from the CPU. ; 


5. When the device handler recognizes that the I/O op- 
eration is complete, it informs RMON and passes 
back the queue element. 


6. The job that issued the I/O request is set runnable by 
RMON. Another scheduling pass is done and the job 
continues execution when control is returned to it. 


Transfers to Block Replaceable Devices 


When using block replaceable devices such as disks, re- 
member that all I/O transfers start at the beginning of a block. 
So if you read ten words from block 0 and then issue a re- 
quest for another ten words from block 0, you read the same 
ten words again. Also, remember that if a write operation 
leaves a part of a block empty, the remainder of the last block 
is filled with zeros. 

Because of these block replaceable device features, you 
should always transfer data in units of a block (256 words). 
If you must update data in the center of a block, you should 
read the block, update the data in memory, and write the 
modified block. 

When you issue a read or write request on a channel, 
RMON checks the request to make sure that the block 
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number is within the file. If the block number is outside 
the file, RMON returns an end-of-file error and no data is 
transferred. 

If the first block of the transfer is inside the file, RMON 
checks to make sure that the last block of the transfer is also 
in the file. If the file is too short for the transfer, RMON ad- 
justs the word count to make the transfer fit the file. So, on 
block replaceable devices, an end-of-file error is returned 
only if the block number given in the request is past the 
end of the file. 


Transfers to Sequential Devices 


The end-of-file processing for sequential devices is com- 
patible with that for block replaceable devices. If the data 
to be read is not at the end of the file, as much data as pos- 
sible is transferred and no I/O error is generated. An end- 
of-file error is generated only if the device is at the end of 
the file when you make the request. 


Closing a Channel 


You must always close an open channel when you want to 
use that channel for another file or when the channel was 
opened using ENTER and you want to keep the data writ- 
ten to it. 

You may exit without closing a channel if the channel 
was opened with LOOKUP, or if the channel was opened 
by ENTER but was used as a scratch file for data to be dis- 
carded. If you exit without closing the file, the file will be 
erased. 

The CLOSE request closes a file correctly. If it was 
opened with an ENTER request, the file has its name en- 
tered in the directory. The channel is disconnected from the 
file and cannot be used until it is opened again. 

The PURGE request for MACRO—11 and FORTRAN IV 
programmers is provided for use when you have used 
ENTER to open a file that is not to become permanent. The 
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PURGE request disconnects the channel from the file, and 
the file is lost. The MACRO—11 requests have the form: 


.CLOSE/.PURGE chan 
The FORTRAN IV calls have the form: 


CALL CLOSEC/PURGE(chan) 


Releasing a Device Handler 


Releasing a device handler makes its memory space avail- 
able for program use. This function is available only to 
MACRO-11 programs; there is no similar call in FOR- 
TRAN IV. 

To reuse space efficiently, release device handlers in 
reverse order to their fetching. If you are releasing only some 
of the device handlers, find the address of the lowest one 
by using the DSTATUS request (discussed later) before re- 
leasing it. Remember to subtract the size from the pointer 
returned by the .DSTATUS request. To release all of the 
device handlers in one operation, use the .SRESET com- 
mand. To release a specific device handler from memory, 
the MACRO-11 programmer uses the .RELEAS request in 
the form: 


-RELEAS dnam 


In this request, ‘‘dnam”’ is the address of the RAD50 device 
name. 


Data Structures 


The programmed requests that allow you to use the RT—11 
queued I/O system require a number of different data items. 
You must provide some of these in your program; others 
are generated by the operating system. 
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User-created File Specifications 


You must specify device names to be used in the fetching 
operation, and file specifications to open channels. Device 
and file names are specified in one- and three-word data 
blocks, encoded in the RAD50 format discussed in chapter 
10, “Controlling Program Execution.” You may combine 
these items into one four-word block. 


System-maintained Channels 


The system maintains a five-word data block for each 
channel, with 16 channels available to each job by default. 
Figure 44 is a schematic diagram of this five-word data block. 
The data block for a specified channel is filled in when the 
channel is opened. The data block is accessed by the sys- 
tem when: 


¢ A read or write request is issued. The data is checked 


for trying to read or write past the end of the file and 


Figure 44. 
Input/Output Channel Data Block 


OFFSET CONTENTS 


Le CHANNEL STATUS WORD 
STARTING BLOCK NUMBER OF THIS FILE 
2 (O iS NONFILE—STRUCTURED) 
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then used to build the I/O queue element for the re- 
quest (discussed later). 


¢ A new file is closed. The on block is used to update 
the directory. 


C.USED is undefined if the channel is opened by a 
LOOKUP request. If opened by an ENTER, the value of 
C.USED is the number of the highest block written. 

If your program needs more than 16 channels, you can 
use the programmed request .CDFN to request the total 
number of channels you want. Each .CDFN request 
supersedes any previous .CDFN request. The MACRO-11 
form of the .CDFN request is: 


.CDFN  area,addr,ynum 


In this. request: 


area is the address of a three-word EMT argument 
block. 
addr is the address of an area-you have reserved in 


your program for use as channel tables. The 
size of the area must be 5*num words. 


num is the total number of channels you want 
(maximum of 255). 


sp erparmticeannoeceer aes een 


EXAMPLE 


-CDFN #EMTBLK,#AREA, #26 


Pe 


be I 


You use the FORTRAN IV system subroutine ICDFN 
in the form: 


IERR = ICDFN(num) 


Here “‘num”’ is the total number of channels you want. The 
memory for the channel tables is taken from the FORTRAN 
IV OTS workspace. 
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System-maintained I/O Queue Elements 


The system maintains a seven-word queue element under 
the SJ and FB monitors, and a ten-word element under the 
XM monitor. One queue element is created for each job. The 
contents of an I/O queue element are shown in figure 45. 
The queue element is used in the following ways: 


¢ It is filled in by RMON in response to a read or write 
request. 


¢ RMON passes the queue element to the device han- 
dler, which uses it while servicing a read or write 
request. 


¢ When the device handler has completed the execu- 
tion of the I/O request, it passes the queue element 
back to RMON. | 7 


When not in use, a job’s queue elements are kept in a 
list of available elements. When a job issues a request that 
needs a queue element, one is removed from the list. I/O 
requests, inter-job communication requests, and timer re- 
quests all require queue elements. When an operation us- 
ing a queue element completes, the queue element is re- 
turned to the list. 

As previously discussed, one queue element is avail- 
able to each job. If your program needs more than one queue 
element, you can use the .QSET request. This condition will 
be discussed in chapter 15, “Using Nonsynchronous Queued 
Input/Output.” 

In the .QSET request, you specify the number of queue 
elements you want added to the list, rather than the total 
number of elements. The MACRO—11 request form is: 


.QSET addr, num 


In this request, ‘“‘addr” is a block of memory you have re- 
served to be used for queue elements. The size of this area 
must be 7*num under the SJ or FB monitor and 10*num 
under the XM monitor. Here ‘“‘num”’ is the number of ad- 
ditional queue elements you want to reserve. 
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Figure 45. 
Structure of an Input/Output Queue Element 


NAME OFFSET CONTENTS 
Q.LINK . LINK TO NEXT QUEUE ELEMENT; OIF NONE 


Q.BLKN 


PHYSICAL BLOCK NUMBER 


RESERVED JOB DEVICE SPECIAL 
NUMBER UNIT FUNCTION 
(4 BITS) (3 BITS) CODE 


0=BG (8 BITS) 


USER BUFFER ADDRESS (MAPPED THROUGH PAR1 
WITH Q.PAR VALUE, IF XM) 


IF<0, OPERATION IS WRITE 
WORD COUNT IF =0, OPERATION IS SEEK 

IF>0, OPERATION IS READ 
THE TRUE WORD COUNT IS THE ABSOLUTE 
VALUE OF THIS WORD. 


Q.cSw 2 POINTER TO CHANNEL STATUS WORD IN I/O 
| CHANNEL (SEE FIGURE 3-29) 
6 
7 * 
7 


(1 BIT) 


COMPLETION ‘{ IF 0, THIS IS WAIT MODE 1/0 


ROUTINE iF 1, JUST QUEUE THE REQUEST 
CODE AND RETURN 
IF EVEN, COMPLETION ROUTINE 
ADDRESS 


PAR1 VALUE (XM ONLY) 
RESERVED (XM ONLY) 
RESERVED (XM ONLY) . 


The name of the FORTRAN IV request is IQSET which 
has the form: 


TERR =IQSET(num) 
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Here ‘‘num”’ is the number of additional queue elements to 
be allocated. The memory for these additional elements is 
taken from the FORTRAN IV OTS workspace. 


Device Handlers 


A device handler is a software routine that performs the 
operations necessary to allow a device to respond to I/O re- 
quests as planned. Device handlers may be either perma- 
nently resident in memory, or installed and removed as 
needed by your program. Before your program can request 
I/O to any device, the device handler for that device must 
have been placed in memory. You can do this in three dif- 
ferent. ways: 


1. Permanently resident. The handler for the system de- 
vice (SY:) is always resident; the TT: handler is resi- 
dent in FB and XM systems. 


2. Loaded from KMON, using the LOAD command. 


3. Fetched by the program during execution, using a 
programmed request. 


Device handlers to be used by foreground programs 
must be loaded. Background programs can either load or 
fetch handlers from within the program. Loaded handlers 
stay in memory until unloaded from KMON or removed as 
a result of a system reboot. 

Loading a device handler means that your program does 
not have to include instructions to fetch the handler; on the 
other hand, loading from KMON requires the help of an 
operator. Even if you expect that the device handler will be 
loaded before your program is run, you can assure success 
by performing either of the following: 


1. Do a fetch (background jobs only); a fetch for resi- 
dent handler returns immediately, indicating success. 


2. Use the DSTATUS (device status) request in your 
program to check if the handler is resident. Provide 
code to print an error message and exit if it is not. 
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.DSTATUS returns four words of information about the 
specified device. You supply the logical or permanent de- 
vice name. The MACRO-11 form of .DSTATUS is: 


.DSTATUS _ infblk,device 


In this request, ‘‘infblk”’ is the address of a four-word block 
to which the information is returned and ‘‘device’’ is the 
address of a RAD50 word containing the device name. 

The FORTRAN IV system subroutine name for the de- 
vice status request is IDSTAT. Its form is: 


IERR = IDSTAT{(device,infblk) 


Here ‘“‘device’”’ contains a RAD50 word for the device, while 
‘“‘infblk’’ is a four-word area to store the returned informa- 
tion. 

You use the DSTATUS or IDSTAT request to: 


¢ Check for the correct physical device, if it is impor- 
tant that your program access a specific physical 
device. 


¢ Check device characteristics. For example, you may 
want to make sure that your program will not try to 
write to a read-only device. 


e Check the size of the handler before a fetch. 


e Check if a handler is resident. 


Figure 46 shows the information returned by 
DSTATUS or IDSTAT. The following list elaborates the 
DSTATUS function: 


1. DEVICE CHARACTERISTICS. Refer to the previous 
list on uses of DSTATUS or IDSTAT. 


2. DEVICE CODE. A unique number for every physical 
device. A list of these assignments is available in 
chapter 2 of the RT—11 Programmer’s Reference 
Manual. 


3. HANDLER SIZE. This number represents the num- 
ber of bytes. 
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4. POINTER TO HANDLER. If the handler is resident, 
this number is the load point plus 6. If the handler is 
not resident, the value is 0. 


5. DEVICE SIZE. In 256-word blocks. If the device is 
sequential, the value is 0. 


Figure 46. 
DSTATUS Information Block 


DEVICE 
CHARACTERISTICS BEVICE CODE 
HANDLER SIZE 
POINTER TO HANDLER 
DEVICE SIZE 


Practice . Type the program PR1401.MAC or PR1402.FOR into a 
14—1 file. 


Run the program. When it runs successfully, copy it to 
a file called PR1801.MAC or PR1802.FOR for use in 
practice 18-1. 


Change the program so that it copies from a different 
file. 


Change the program so that it reads and writes 512 
words per access instead of 256. 


Reference 


RT—11 Programmer’s Reference Manual. Chapter 2 discusses the 
READW and WRITW requests in detail. 
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Using 
Nonsynchronous 
Queued 
Input/Output 


The architecture of the PDP—11 allows a large number of 
I/O operations to occur in parallel with computation. Thus, 
the PDP—11 enables real-time applications to operate with 
high-speed I/O devices. A slow application program can 
miss high-speed data input or lose control of a high-speed 
output device. 

In chapter 14, ‘Using Queued Input/Output,’ you 
learned how to use a class of I/O requests called synchro- 
nous I/O requests. When you use these requests your pro- 
gram does not proceed with its execution until the re- 
quested I/O completes and, therefore, you do not take full 
advantage of the PDP—11’s capability. In this chapter we 
will discuss another class of I/O requests—nonsynchro- 
nous I/O. Nonsynchronous I/O allows you to make use of 
the I/O architecture by requesting I/O transfers that run 
concurrently with other transfers and with computation. 
Careful use of these requests can greatly increase the exe- 
cution speed of your program. 

The MACRO-11 requests discussed in this chapter are: 
-READ, .WRITE, .WAIT, .READC, and .WRITC. The 
FORTRAN IV requests discussed are: IREAD, IWRITE, 
IWAIT, IREADC, IWRITC, IREADF, and IWRITF. 
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When you have completed this chapter, you will be 
able to select the best mode(s) of I/O to use, given in- 
put/output specifications for a program. The specifications 
may include the average data rate of each I/O channel, the 
amount by which the data rates change, the tradeoff con- 
siderations of throughput against ease of programming, and 
the expected ratio of computing time to I/O duration. 

You will also be able to determine whether through- 
put can be improved by overlapping input, computation, 
or output, given specifications for a program. You will then 
learn to design and implement an algorithm that includes 
such overlapping. Given specifications of a program with 
multiple, independent input channels, you will also learn 
to design and implement the program, using event-driven 
1/0. : 


Nonsynchronous I/O 


Any I/O transfer includes three important events: 


1. Starting the transfer. Your program issues a READ or 
WRITE programmed request. Control leaves the job 
and enters the monitor. The ‘‘request count”’ byte in 
the channel table is incremented. 


2. Returning control to your program. 


3. Assuring completion of the I/O transfer. This means 
that requested input information is available for pro- 
cessing, or that information in an output buffer has 
been transferred and the buffer can be used again. 


When using nonsynchronous I/O, you must take spe- 
cial steps within your program to check for or wait for 
completion of the I/O transfer. This makes programming with 
nonsynchronous I/O more difficult than with synchronous 
V/O. 


/O Modes 
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RT~—11 supports I/O requests in three modes. Each mode has 
its own set of programmed requests, is executed in a dif- 
ferent way, and is more useful in certain types of applica- 
tions. Matching your programming needs to the best I/O 
mode makes the most efficient use of your RT—11 system 
and your programming time. 

You have learned about synchronous I/O. The two 
nonsynchronous modes are asynchronous and event-driven. 
Event-driven I/O is also called I/O with completion rou- 
tines. Both nonsynchronous modes return control to your 
program immediately and therefore, allow you to perform 
other operations while I/O is in progress. They differ, how- 
ever, in the actions that RT—11 takes when the I/O transfer 
completes, and they also differ in the way that you write 
your program in order to use them. 

Use asynchronous I/O in operations where you may 
want to perform other activities after starting the I/O. This 
can be other processing or another transfer request. When 
your program reaches the point where it must wait for I/O 
completion, your job issues a WAIT request. When a WAIT 
request is issued, control leaves the job and RMON does 
not continue execution of that job until all I/O has com- 
pleted on the channel you specified in the WAIT request. 
RMON implements the WAIT using the request count of the 
channel table. When that request count returns to zero, 
RMON once again allows the job to run. 

Asynchronous I/O is somewhat similar to synchro- 
nous I/O. In synchronous I/O the job issues a request and 
immediately asks to be blocked until that request com- 
pletes. In asynchronous I/O, issuing the I/O request is sep- 
arated from the blocking operation, allowing the job to per- 
form other activities before being blocked. Asynchronous 
I/O is most often used: 


¢ To allow I/O on two or more devices to proceed con- 
currently. When control returns from one I/O request, 
the job issues another. 
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¢ To allow I/O to proceed concurrently with computa- | 
tion. The job issues I/O requests and then proceeds 
with computations on data held in memory. 


Event-driven I/O allows you to specify the operations 
that you want performed when I/O completes, while allow- 
ing your program to do other useful work. When your pro- 
gram issues an event-driven I/O request, you specify a rou- 
tine that you have written and ask for the routine to be 
identified as the completion routine for this request. When. 
I/O completes, the job is interrupted, the completion rou- 
tine is run, and control returns to the job at the point of 
interruption. 

Asynchronous I/O is the better choice when your pro- 
gram has only a limited number of operations to perform 
before it must wait and when it is only waiting for the 
completion of I/O on a specific channel. Event-driven I/O 
is more appropriate if: 


¢ Your job can or must continue processing while wait- 
ing for I/O to complete. For example, if your job is 
controlling a real-time process using parameters that 
change because of input information, the job must 
continue to use the old parameters until new ones 
come in. It cannot stop and wait for the new input. 


¢ Your job must wait for a specific I/O request (if mul- 
tiple requests have been issued on the same channel). 


¢ Your job must wait for some combination of requests 
to complete. For example, you may want the job to 
wait until one of a group of selected I/O requests 
completes. . 


Using I/O Queue Elements 


The use of I/O queue elements is transparent for synchro- 
nous I/O. For nonsynchronous I/O, however, if you do not 
make sure you have enough I/O queue elements, your job 
can become blocked, making your program slower. 
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A request for an I/O transfer is an outstanding request 
from the time it is issued until the time it completes. While 
a request is outstanding, the device handler servicing it has 
exclusive use of the queue element for that request. For 
event-driven I/O, this queue element is also kept in use while 
the completion routine is running. 

If you use only synchronous I/O, the one queue ele- 
ment (automatically provided) is enough, -because at any 
given time only one I/O request is outstanding. If you use 
nonsynchronous I/O, the number of outstanding I/O re- 
quests is unlimited. To get the best performance from your 
program, estimate the maximum number of I/O requests that 
will be outstanding at any given time, then use .QSET or 
IQSET to make sure you have enough I/O queue elements. 
If you issue an I/O request and no queue element is avail- 
able, your job is blocked until one becomes available. 


Asynchronous Requests 


The MACRO-11 format for the asynchronous I/O requests 
is: . 


-READ = area,chan,buff,went,block 
WRITE _area,chan,buff,wcnt,block 


The FORTRAN IV format is: 


IERR=IREAD (went,buff,blk,chan) 
IERR=IWRITE (went,buff,blk,chan) 


The arguments are identical to those of the synchronous 
requests. 

You may also use the .WAIT or .[WAIT request in the 
following formats: 


MACRO-11: .WAIT chan 
FORTRAN IV: IERR=IWAIT (chan) 
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When you use .WAIT or IWAIT, you have to wait for all 
I/O on a selected channel to complete. If you want to wait 
for a specific request to complete, do one of the following: 


¢ Use a synchronous request. 


¢ Use an asynchronous request and do not issue any 
other request on that channel before issuing the 
WAIT or IWAIT. 


¢ Use event-driven I/O and have a completion routine 
run when that specific I/O request completes. 


Using Asynchronous 1/0 to Implement 
Multiple Buffering 


Sometimes a program can be handled as three operations: 


¢ Input: the transfer of data from a peripheral device to 
memory 


e Computation: the production of new data in memory 
using data in memory 


¢ Output: the transfer of data from memory to a periph- 
eral device 


The advantage of using a synchronous I/O is that these 
operations can take place concurrently, although they are 
logically sequential. Data must be input before computa- 
tions can be performed, and computations must be com- 
plete before results can be written out. Thus, there are two 
opposing needs: to have the operations take place concur- 
rently to increase speed, and sequentially, for the logic of 
the program. 

This problem can be solved by multiple buffering. In- 
put data is read into a buffer. When that buffer is full, data 
is read into a second buffer while computation starts on the 
first. Each buffer goes through the necessary operations in 
sequence, but simultaneously, one buffer can be in use for 
input, one for output, and one or more for computation. 
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Benefits of Multiple Buffering 


To see how multiple buffering helps, let’s look at a simple 
copy operation which omits the computation step from the 
read/compute/write cycle. Figure 47 shows a synchronous, 
single-buffered copy operation. The box represents the 
buffer. An arrow pointing into the buffer represents a read 


Figure 47. 
Synchronous Single-buffered Copy Sequence 


OPERATIONS 
WRITE READ 
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Figure 48. 
Double-buffered Copy Sequence 


OPERATIONS CODE 
(REQUESTS 


WRITE READ AND BUFFER) 


READW A 


WRITE A 
READ B 


WAIT A 
WAIT B 
WRITE B 
READ A 


WAIT B 
WAIT A 
WRITE A 
READ B 


WAIT A 
WAIT B 


WRITE B 
READ A 


WAIT B 
WAIT A 


operation, and another arrow pointing out of the buffer 
represents a write. The figure indicates how time is di- 
vided among the read and write operations over three cy- 
cles of the program. 

Figure 48 shows a double-buffered copy. By using two 
buffers, the READ and the WRITE can execute concur- 
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rently. This figure shows the overlap of these operations. 
As you study the figure, please read the following notes: 


1 Instead of using a READW, you could use a READ 
followed by a WAIT. This may make the program eas- 
ier to write. 


2 The order in which you issue the READ, WRITE, and 
WAIT requests generally makes no significant differ- 
ence if the input and output devices are of approxi- 
mately the same speed. For example, if you know that 
the output device is slower than the input device, is- 
sue the WRITE on that channel first and the WAIT on 
that channel last. 


3 If you switch either the order of the READ and 
WRITE, or the order of the WAITs from that shown in 
figure 48, you can change the second I/O request to 
synchronous mode and remove the first WAIT. There 
will be a small increase in speed because you are per- 
forming only one programmed request instead of two. 
The gains are probably not significant, however. 


Figure 49 compares single buffering with double 
buffering. The longer the programs run, the more time is 
saved. In the long run, execution time can be decreased by 
up to 50 percent using this method. 

Figure 50 shows a flowchart of a double-buffered copy 
program. End-of-file and error conditions have been omit- 
ted to keep the flowchart simple. Following this figure, are 
MACRO-—11 and FORTRAN IV programs that carry out this 
double-buffered copying method. 

Two conditions have been assumed in figures 47 
through 50 and the two programs (PR1501.MAC and 
PR1502.FOR): 


1. The input and output devices are not the same. If 
they were, a program using two buffers would run no 
faster than a single-buffered program, because the de- 
vice handler is able to service only one request at a 
time. 

If a device handler is to control a number of devices 
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that can, in fact, operate independently, you will 
need to write a device handler that queues I/O re- 
quests internally and thereby avoids the normal seri- 
alization of the queued I/O system. Only if you are 
working with this sort of device handler, can you 
overlap operations that are being performed by it. 


2. The time graphs show approximately equal input and 
output times. This is the condition in which a dou- 
ble-buffered copy program is more efficient. The 
greater the difference between the speed of the input 
device and that of the output device, the smaller the 
benefit of a double-buffered copy over a single- 
buffered copy. 


Figure 49. 
Comparison of Single- and Double-buffered Copy 
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Figure 50. 
Flowchart for a Double-buffered Copy Program 


FLAG BUFFER ‘A’ 
AS INPUT BUFFER 


FLAG BUFFER ‘B’ 
AS OUTPUT BUFFER 


READ INTO 
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WAIT ON BOTH 
CHANNELS 
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Using Multiple Buffering with Computation 


Input and output operations on the same device cannot be 
overlapped with each other, but both I/O operations can be 
overlapped with computation. Buffering arrangements dif- 
fer depending on which operations overlap. 

Some types of computation need the input data to be 
kept until the computation is complete. For this type of 
computation, you need another buffer to hold results. Other 
computations can store results by writing over the input 
data, so you do not need to allocate a separate output buffer. 
Whether you use separate input and output buffers, of 
course, will affect the multiple buffering algorithm that you 
use. 
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PR1501.MAC -TITLE FILE COPY PROGRAM 


This program copies one file and then exits. 


-MCALL .EXIT -FETCH .LOOKUP .ENTER- .PRINT 
-MCALL .READ «WRITE .CLOSE .SRESET .WAIT 
-MCALL .QSET 
EMTARG: .BLKW 6 ;EMT argument block 
INFILE: .RADSO /DK TRAN1 XYZ/ ;Copy from DK: TRAN1.XYZ 
QUTFIL: .RADSO /DK TRAN2 XYZ/ 3; = to DK: TRAN2.XYZ 
LIMITS: .LIMIT sHigh/low limits 
BUFF 1: .BLKW 256. ;File 1/0 Buffer 1 
BUFF2: .BLKW 256. sFile I/0 Buffer 2 
QELMT: .BLKW 10. sQueue element 
ERROR: ~ BYTE ;Error status byte 
ANNCE: .ASCIZ “Program copies TRAN1.XYZ to TRAN2.XYZ" 
FCHIMS: .ASCIZ “Error on FETCH of output handler" 
FCH2MS: .ASCIZ “Error on FETCH of input handler" 
LKPMES: .ASCIZ “Error on LOOKUP of input file" 
ENTMES: .ASCIZ “Error on creation of output file” 
RERRMS: .ASCIZ “Read error, copy aborted" 
WERRMS: .ASCIZ “Write error, copy aborted” 
PRTCT: .ASCIZ “Protected output file already exists" 
- EVEN 
-SBTTL SETUP -- Setup Files For Copy 


This routine sets up files for I/O. 
The file specifications are fixed. 
Returns with C-Bit SET on error. 


MOV R1,-CSP) ;Save register 
-PRINT #ANNCE ;Announce program 
Fetch device handlers 
MOV LIMITS+2,R1 ;Load high limit 
-FETCH R1,#OUTFIL 3Get output handler 
BCS FCHIER s;Branch on FETCH error 
MOV RO,R1 ;Load high limit 
-FETCH R1,#INFILE 3Get input handler 
BcS FCH2ER ;Branch on FETCH error 
Open files 
~LOOKUP #EMTARG, #3,#INFILE 
BCS LKPERR ;Branch on OPEN failure 
MOV RO,R1 ;Load input file length 
-ENTER #EMTARG,#0,#OUTFIL 
BCC DONE s;Branch on success 
Error Routines 
PRINT #ENTMES . ;Issue create failure msg 
BR ERDONE s;And finish up 

LKPERR: .PRINT #LKPMES ;Issue open failure msg 
BR ERDONE 3And finish up 
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PR1501.MAC FCH2ER: .PRINT #FCH2MS sIssue FETCH error msg 
(continued) BR ERDONE 3And finish up 
FCH1ER: .PRINT #FCHIMS ;Issue FETCH error msg 
ERDONE: SEC sIndicate error occurred 
DONE: MOV CSP)+,R1 sRestore R1 Csave C-bit) 
RETURN sReturn to caller 
-SBTTL CPYRTN -- Double-Buffered Copy 


Routine copies data from the opened input file 
on channel 3 to the output file opened on 
channel 0. 

Returns with C-BIT set on error. 


Note: All registers except RO are preserved. 


CPYRTN: MOV R1,-CSP) ;Save registers 
MOV R2,-CSP) 
MOV R3,-CSP) 
MOV R4,-CSP) 
-QSET #QELMT, #1 sAllocate a queue element 
CLR R1 sInitialize block number 
MOV #BUFF1,R2 ;R2 ==> input buffer 
MOV *BUFF2,R3 ;R3 ==> output buffer 
CLRB ERROR ;Clear error flag 
-READ #EMTARG, #3,R2, 256. ,R1 
BCC 2$ ;Branch if read succeeded 
TSTB a#S2 sEnd-Of-File CEOF)? 
BEQ EXIT sBranch if so 
BR RDERR ;Otherwise, process error 
WAIT #0 sWait for write to finish 
BcS WERR ;Branch on error 
»WAIT #3 sWait for read to finish 
BCS RDERR s;Branch on error 
MOV R2,R4 ;Switch input & output 
MOV R3,R2 ; buffers 
MOV R4,R3 
WRITE #EMTARG, #0,R3,#256.,R1 
BCS WERR s;Branch on write error 
3$: INC R1 ;Update block number 
BR 1$ 3;And read next block 
RDERR: .PRINT #RERRMS ;Issue read error msg 
BR EREXIT 3And finish up 
WERR: -PRINT #WERRMS ;Issue write error msg 
EREXIT: DECB ERROR ;Set error flag 
EXIT: MOV CSP)+,R4 ;Restore saved registers 
MOV CSP)+,R3 
MOV CSP)+,R2 
MOV CSP)+,R1 
-WAIT #0 ;Wait for last output 
BCC 1$ s;Branch if successful 
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PR1501.MAC 
(continued) — 


Programming with RT—11 


1$: 


2$: 
3$: 


CLSCHN: 


PRGCHN: 
RESET: 


«PRINT 
BR 
TSTB 
BEG 
SEC 
RETURN 
.SBTTL 
- CLOSE 
»- CLOSE 
BCC 
-PRINT 


- SRESET 
RETURN 
-SBTTL 
CALL 
BCS 
CALL 
BCS 
CALL 
BR 
CALL 
EXIT 
-END 


#WERRMS ;Issue write error msg 

2s 

ERROR ;Error? (Clear C-BIT) 

3$ s;Branch if not 
sOtherwise, set C-BIT 
sReturn to caller 

CLSCHN -- Cleanup For Copy Program 

#3 ;Close input file 

#0 ;Close output file 

RESET sBranch if succeeded 

#PRTICT ;Issue protected file msg 
;Purge files 
;Reset system & purge 
sReturn to caller 

MAIN PROGRAM 

SETUP ;Open input & output files 

1$ ;Branch if failed 

CPYRTN ;Copy the input to output 

1$ ;Branch if failed 

CLSCHN s;Close the files 

2$ sExit 

PRGCHN ;Purge the files 
sExit 

START 
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PR1502.FOR PROGRAM COPY 1 


Program performs a file to file copy and then 
exits. 


LOGICAL*1 SETUP,CPYRTN 
LOGICAL*1 ERROR 


ERROR = SETUPC) ! Open files 

IF CERROR) GO TO 20 ! Stop on setup error 

ERROR = CPYRTNC) ! Copy input to output file 
IF CERROR) GO TO 20 ! Stop on error 

CALL CLSCHN §' Success, close channels 
GO TO 30 

CALL PRGCHN ! Error, purge channels 
CALL EXIT 

END 

FUNCTION SETUP 


This routine sets up the files for I/O. 
The file specifications are fixed in this version. 


Function returns .TRUE. if an error occurred. 


LOGICAL*1 SETUP 
INTEGER*2 INCHN,OUTCHN 
COMMON /CHNNLS/ INCHN,OUTCHN 


Channel numbers are common because they are used 
by CPYRTN, CLSCHN, and PRGCHN. 


INTEGER*2 INFILEC4),QOUTFILC4) 
DATA INFILE/2RDK,3RTRA,2RN1,3RXYZ/ !$ Input & output 
DATA OUTFIL/2RDK,3RTRA,2RN2,3RXYZ/ ! file specs 


Qutput introductory message and allocate channels. 
CALL PRINTC’Program copies TRAN1.XYZ to TRAN2.XYZ") 
INCHN = IGETCC) 

QUTCHN = IGETCC) 


Fetch device handlers. 


IF CIFETCHCOUTFILC1)) .NE. 0) GO TO 101 
IF CIFETCHCINFILEC1)>) .NE. 0) GO TO 102 


Open input file. 


LENGTH = LOQKUPCINCHN, INFILE) 
IF CLENGTH .LT. 0) GO TO 103 
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PR1502.FOR 
(continued) Create. output file. 


IF CIENTERCOUTCHN,OUTFIL,LENGTH) .LT. 0) GO TO 104 
SETUP = .FALSE. ' Return success 
RETURN 


ERROR ROUTINES 


CALL PRINTC’Error FETCH of output handler’) 
GO TO 200 

CALL PRINTC’Error FETCH of input handler’) 
GO TO 200 

CALL PRINTC’Error LOOKUP of input file’) 

GO TO 200 

CALL PRINTC’Error creation of output file’) 
SETUP = .TRUE. ! Return with error 
RETURN 

END 

FUNCTION CPYRTN 


Double buffered copy routine. 


Function returns .TRUE. on error. 
NOTE: Some severe errors will abort the program. 


LOGICAL*1 CPYRTN 

INTEGER*2 INCHN,QUTCHN 

COMMON /CHNNLS/ INCHN,OUTCHN 

INTEGER*2 BUFFERC256,2),BLOCK,INPTR,OUTPTR 

LOGICAL*1 FRSTTM ! "First time through" flag 
DATA FRSTTM/.TRUE./ 

IF €.NOT. FRSTTM) GO TO 10 ! Do QSET only once 

IF CIQSETC1) .NE. 02 STOP ’No room for queue element’ 
FRSTTM = .FALSE. 

BLOCK = 0 ! Initialize block number 
INPTR = 1 Initialize input buffer # 
OUTPTR = 2 Initialize output buffer # 


Read/write loop. Begin by reading into first buffer. 


IERR = IREADC2S6,BUFFERC1,INPTR), BLOCK, INCHN) 
IF CIERR .GE. 0) GO TO 30 ! Successful read 

IF CIERR .EQ@. €-1)) GO TO 150 ! End of File 
GO TO 100 ! Otherwise, error 


Wait for read and previous write to finish. 


IF CIWAITCINCHN) .NE. 0) GO TO 100 ! Error on read 
IF CIWAITCOUTCHN) .NE. 0) GO TO 100 ! Error on write 
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PR1502.FOR 
(continued) Switch read and write buffers. 


ITMP = INPTR 
INPTR = OUTPTR 
OUTPTR = ITMP 


Write out buffer just read. 


IF CIWRITEC2S6,BUFFERC1,OUTPTR),BLOCK,QUTCHN) .LT. 
GO TO 101 

BLOCK = BLOCK+1 ! Update block number 

GO TO 20 ! Read next block 


ERROR ROUTINES 


CALL PRINTC’Read error, copy aborted’) 
GO TO 140 ; 
CALL PRINTC’Write error, copy aborted’) 
CPYRTN = .TRUE. 

RETURN 


Wait for output to complete and return success. 


IF CIWAITCOUTCHN) .NE. 0) GO TO 101 
CPYRTN = .FALSE. 

RETURN 

END 

SUBROUTINE CLSCHN 


Close files. 


INTEGER*2 INCHN,QUTCHN 

COMMON /CHNNLS/ INCHN,OUTCHN 

CALL CLOSECCINCHN) 

IF CICLOSECOUTCHN) .EQ. 4) CALL PRINT 
C’Protected output file already exists’) 

RETURN 

END 

SUBROUTINE PRGCHN 


Purge channels. 


INTEGER*2 INCHN,OUTCHN 
COMMON /CHNNLS/ INCHN,OUTCHN 
CALL PURGECINCHN) 

CALL PURGECOUTCHN) 

RETURN 

END 
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While examining the following programs (PR1503.MAC 
and PR1504.FOR) and designing multiple buffering algo- 
rithms of your own, remember these rules: 


1. For maximum speed, start I/O as early as possible to 
achieve the most overlap. 


2. Do not start I/O on a buffer until all other activity on 
that buffer has completed: 


* Do not start writing from a buffer until the computa- 
tions that produce the data in the buffer have finished. 


¢ Do not read into a buffer until the computations that 
need the old data in the buffer have finished. 


¢ If an input buffer is also being used as an output buffer, 
do not read into that buffer until the previous write op- 
eration on that buffer has completed. 


_3. Do not start computation on input data until you are 


sure that the READ request into that buffer has com- 
pleted. 


4. The WAIT request waits until all I/O on a channel is 
done. If you are using asynchronous I/O and you 
want to wait for a specific I/O transfer to complete, 
do not start a new transfer on that channel until you 
first execute a WAIT. 


Figure 51 shows the sequence of operations in a 
read/compute/write program. In this example the input and 
output devices are the same, so the program does not try to 
overlap input and output. In addition, the computation can 
store its results in the input buffer. The circular arrow rep- 
resents the computation operation. 

In addition to showing the steps in the operation, fig- 
ure 51 shows when the program is active—not waiting for 
I/O to complete. The actual timing depends on the relative 
speeds of the I/O device and the computation. In the figure, 
the timing and spacing is exaggerated to emphasize the 
connections among the different events and to show poten- 
tial overlaps. Overlap is greatest when the total I/O time is 
about the same as the computation time. Then you can save 
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Figure 51. 
Double-buffered Read/Compute/Write Sequence 


OPERATIONS 


WRITE ACTIVE 
COMPUTE | (NOT 


READ | BLOCKED) NOTES 
READW A 


WRITE A 
WAIT B 


WRITE B 
WAIT A 


WRITE A 
WAIT B 


RETURN TO sTEP [4 ] 


as much as 50 percent of the time. The program is blocked 
only when it must wait for the latest read operation to 
complete. The numbered notes in figure 51 are described 
below. 


1 Instead of a READW, you can use a READ followed 
by a WAIT. This makes the program easier to write. 
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2 Assuming the READ operation takes approximately 
half the time of the computation, the READ B opera- 
tion in frame 2 completes while the COMPUTE A is 
in progress. Therefore, the following WRITE A starts 
executing immediately and the WAIT B is not neces- 
sary—it would return successfully right away. The 
dotted lines indicate this. WAIT B is included, and 
the solid lines are positioned to show the sequence of 
requests and the pattern of the operations that are set 
up soon after the startup. 


3 Each of these WRITEs starts to execute as soon as the 
previous READ completes. 


4 Each of these READs starts to execute as soon as the 
previous WRITE completes. 


Figure 52 is a flowchart for the double-buffering me- 
thod shown in figure 51. The two programs (PR1503.MAC 
and PR1504.FOR) which follow are examples of this dou- 
ble-buffering method. The programs read a specified file from 
DK:, sort the bytes of each block, and write the results to 
another file on DK:. Figure 53 is a flowchart for a program 
whose computation needs a separate output buffer. To 
overlap operations here, you need four buffers. At any given 
time, one pair is being used for I/O (read into the input buffer 
and write from the output buffer) and one pair is being used 
in computation. This flowchart also allows for different in- 
put and output devices. 

The use of the WAIT request is probably the most dif- 
ficult part of writing a program which uses multiple buffers. 
In this type of program, the WAIT on the input channel must 
precede the start of computation on that buffer. 

If the input and output devices are not the same, a wait 
on output channel is needed before the read into input 
buffer, to make sure that the old buffer contents are written 
out before the new contents are read in. If the devices are 
the same (as assumed in these examples), the device han- 
dler does not start the READ until it has completed the 
WRITE. 
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Figure 52. 
Flowchart for Double-buffered Read/Compute/Write Program 


READ INTO BUFFER ‘A’ 


FLAG BUFFER ‘A’ AS 
COMPUTE/OUTPUT 
BUFFER 

FLAG BUFFER ‘B’ AS 
INPUT BUFFER 


WAIT ON INPUT 
CHANNEL (I.E. 

WAIT FOR COMPUTE/ 
OUTPUT BUFFER 

TO BE FULL) 


READ INTO INPUT 
BUFFER 


DO COMPUTATIONS 


ON COMPUTE/ 
OUTPUT BUFFER 


WRITE COMPUTE/ 
OUTPUT BUFFER 


SWITCH BUFFER 
FLAGS 
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PR1503.MAC 


Programming with RT—11 


EMTARG: 
INFILE: 
OUTFIL: 
LIMITS: 


BUFF 1: 
BUFF2: 
QELMT: 
ERROR: 
EOF: 

ANNCE: 


FCH1MS: 
FCH2MS: 
LKPMES: 
ENTMES: 
RERRMS: 
WERRMS: 


PRTCT: 


-TITLE COMPUTATION & I/0 EXAMPLE PROGRAM 


This program demonstrates asynchronous double 
buffered computation. The program reads data 
from an input file, performs computation on 
the data read, and writes the transformed 
data to the output file. 


-MCALL .EXIT -FETCH .LOOKUP .ENTER’ .PRINT 
-MCALL .READ -WRITE .CLOSE .SRESET .WAIT 
-MCALL .QSET 

-BLKW 6 ;EMT argument block 
»RADSO /DK TRAN1 XYZ/ ;Copy from DK: TRAN1.XYZ 
»RADSO /DK TRAN2 XYZ/ 3; to DK: TRAN2.XYZ 
-LIMIT sHigh/low program limits 
- BLKW 2S6. ;File I/O Buffer 1 

» BLKW 256. sFile I/0 Buffer 2 

- BLKW 10. sQueue element 

«BYTE ;Error. status byte 

» BYTE ;End of File flag 
-ASCIZ “Program copies TRAN1.XYZ to TRAN2 
-ASCIZ “Error on FETCH of output handler" 
-ASCIZ “Error on FETCH of input handler™ 
-ASCIZ “Error on LOOKUP of input file" 

-ASCIZ “Error on creation of output file” 
-ASCIZ “Read error, copy aborted" 

-ASCIZ “Write error, copy aborted" 

-ASCIZ “Protected output file already exists" 
- EVEN ; 

-SBTTL SETUP -- Setup Files For Copy 


This routine sets up files for I/O. 
The file specifications are fixed. 


Returns with C-Bit SET on error. 


MOV R1,-CSP) ;Save register 

-PRINT #ANNCE ;Announce program 
Fetch device handlers 

MOV LIMITS+2,R1 ;Load high limit 
-FETCH R1,#OUTFIL ;Get output handler 
BCS FCH1ER ~  $Branch on FETCH error 
MOV RO,R1 ;Load high limit 
FETCH RO,#INFILE ;Get input handler 

BcS FCH2ER sBranch on FETCH error 
Open files 

»-LOOKUP #EMTARG, #3,#INFILE 

BCS LKPERR ;Branch if open failed 
MOV RO,R1 ;Load input file length 


PR1503.MAC 
(continued) 
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-ENTER #EMTARG, #0, #OUTFIL 
BCC DONE ;Branch if successful 
3 Error Routines 
-PRINT #ENTMES ;Issue create failure msg 
BR ERDONE sAnd finish up 
LKPERR: .PRINT #LKPMES ;Issue open failure msg 
BR ERDONE 3And finish up 
FCH2ER: .PRINT #FCH2MS sIssue FETCH error 
BR ERDONE ;And finish up 
FCHIER: .PRINT #FCH1IMS ;Issue FETCH error 
ERDONE: SEC sIndicate error occurred 
DONE: MOV CSP)+,R1 sRestore R1 Csave C-bit) 
RETURN sReturn to caller 
-SBTTL CMPRTN -- Computation Routine 
3 Routine assumes the input file is opened on 
: channel 3 and the output on channel 0. 
5 Returns with C-BIT SET on error. 
g Note: All registers except RO are preserved. 
CMPRTN: MOV R1,-CSP) ;Save registers 
MoV R2,-CSP) 
MOV R3,-(CSP) 
MoV R4,-CSP) 
MoV RS,-(CSP) 
-QSET *#QELMT, #1 sAllocate a queue element 
BEG: » READ #EMTARG, #3, #BUFF1,#2S6. ,#0 
BCC INIT s;Branch if read ok 
TSTB e*52 sEnd-of-File? 
BEG EXIT sBranch if so, all done 
BR RDERR sIssue read error 
INIT: MOV #1,R1 s;Load read block number 
CLR RS sLoad write block number 
MOV *#BUFF2,R2 3;R2 ==> input buffer 
MOV #BUFF1,R3 ;R3 ==> output buffer 
CLRB ERROR sClear error flag 
CLRB EOF ;Clear EOF flag 
SLOOP: .WAIT #3 j;Wait for input to finish 
BcS RDERR sBranch on error 
.READ #EMTARG, #3,R2,4256.,R1 
BCC comP ;Branch if read succeeded 
TSTB e*52 sEnd-Of-File CEOF)? 
BNE RDERR s;Branch if fatal error 
INCB EOF ;Set EOF encountered flag 
? 
3 Perform computation on previously read block. 


Computation in this program consists of shifting 
each data element one place to the right (a 
simple scaling operation). 


154 


PR1503.MAC 
(continued) 
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DERR: 
WERR: 


EREXIT: 
EXIT: 


1$: 


2$: 
3$: 


CLSCHN: 


PRGCHN: 
RESET: 


MOV #256. ,R0 sInitialize counter 

MOV R3,R4 ;Copy buffer address 

ASR CR4)+ ;Shift right one bit (/2) 
DEC RO ;Decrement loop counter 
BNE LOOP s;Branch if not done 


Write out buffer on which computation has just 
been performed. 


«WRITE #EMTARG, #0,R3,#256.,R5 

BCS WERR sBranch on write error 
TSTB EOF sEOF on last read? 

BGT EXIT s;Branch if so 

MOV R2,R4 ;Otherwise, switch input 
MOV R3,R2 ; and output buffer 

MOV R4,R3 

INC R1 ;Update input block # 
INC RS ;Update output block # 
BR SLOOP sAnd continue 


Error messages and cleanup. 


-PRINT #RERRMS ;Issue read error msg 

BR EREXIT 3;And finish up 

-PRINT #WERRMS ;Issue write error msg 

DECB ERROR ;Set error flag 

MOV CSP)+,RS ;Restore saved registers 

MoV CSP)+,R4 

MOV CSP)+,R3 

MOV CSP)+,R2 

MOV CSP)+,R1 

WAIT #0 ;Wait for last output 

BCC 1$ ;Branch if successful 

-PRINT #WERRMS ;Issue write error msg 

BR 2$ 

TSTB ERROR ;Set C-Bit? Cclear it) 

BEG 3$ sBranch if not 

SEC sOtherwise, set it 

RETURN sReturn to caller 

-SBTTL CLSCHN -- Cleanup For Copy Program 

-CLOSE #3 ;Close input file 

-CLOSE #0 ;Close output file 

BCC RESET ;Branch on success 

«PRINT #PRTCT ;Issue protected file msg 
;Purge files 

-SRESET ;Reset Cpurge files) 

RETURN sReturn to caller 

-SBTTL MAIN PROGRAM 

CALL SETUP ;Open files 

BCS 1$ ;Branch on error 
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PR1503.MAC CMPRTN ;Transfer the file 

(continued) 1$ ;Branch on error 
CLSCHN ;Close the files 
2$ 


PRGCHN ;Purge the files 


START 
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PR1504.FOR 


Programming with RT—11 


qan0aogoaonananaandana 


PROGRAM ACOMP 
Asynchronous Double-Buffered I/0 w/Computation. 


This program reads data from the input file, 
performs computation on the data read, and 
writes the transformed data to the output file. 
This program uses asynchronous I/0 to allow the 
computation to occur during 1/0 operations. 


LOGICAL*1 SETUP,CMPRTN 
LOGICAL*1 ERROR 


ERROR = SETUPC) ! Open files 

IF CERROR? GO TO 20 ! Stop on setup error 
ERROR = CMPRTNC) ! Copy file 

IF CERROR) GO TO 20 ! Stop on error 

CALL CLSCHN ! Close channels 

GO TO 30 ! Exit 

CALL PRGCHN ! Purge channels 

CALL EXIT 

END 

FUNCTION SETUP 


This routine sets up the files for I/0. 
The file specifications are fixed in the version. 


Function returns .TRUE. if an error occurred. 
LOGICAL*1 SETUP 


INTEGER*2@ INCHN,OUTCHN 
COMMON /CHNNLS/ INCHN,OUTCHN 


Channel numbers in common because they are used 
by CMPRTN, CLSCHN, and PRGCHN. 


INTEGER*2 INFILEC4),OUTFILC4) 
DATA INFILE/2RDK,3RTRA,2RN1,3RXYZ/ ! Input & output 
DATA OUTFIL/2RDK,3RTRA,2RN2,3RXYZ/ ! file specs 


Output introductory message and allocate channels. 
CALL PRINTC’Program copies TRAN1.XYZ to TRAN2.XY2’) 
INCHN = IGETCC) 

QUTCHN = IGETCC) 


Fetch needed device handlers. 


IF CIFETCHCOUTFILC1)) .NE. 0) GO TO 101 
IF CIFETCHCINFILEC1)) .NE. 09 GO TO 102 
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PR1504.FOR 
(continued) Open input file. 


LENGTH = LOOKUPCINCHN, INFILE)D 
IF CLENGTH .LT. 0) GO TO 103 


Create output file. 


IF CIENTERCOUTCHN,OUTFIL,LENGTH) .LT. 0) GO TO 104 
SETUP = .FALSE. ! Return success 
RETURN 


ERROR ROUTINES 


CALL PRINTC’Error FETCH of output handler’) 
GO TO 200 

CALL PRINTC’Error FETCH of input handler’) 

GO TO 200 

CALL PRINTC’Error LOOKUP of input file’) 

GO TO 200 

CALL PRINTC’Error creation of output. file’) 
SETUP = .TRUE. ! Return error 

RETURN 

END 

FUNCTION CMPRTN 


Double-buffered computation routine. 


Function returns .TRUE. on error. 
NOTE: Some severe errors will abort the program. 


LOGICAL*1 CMPRTN 

INTEGER*2 INCHN,OUTCHN 

COMMON /CHNNLS/ INCHN,OUTCHN - 

INTEGER*2 BUFFERC2S56,2),BLOCK, INPTR,OUTPTR 

LOGICAL*1 FRSTTM ! Once only flag 

DATA FRSTTM/.TRUE./ 

IF €.NOT. FRSTTM) GO TO 10 ! Do QSET only once 

IF CIQ@SETC1) .NE. 02 STOP ‘No room for queue element’ 
FRSTTM = .FALSE. 


Begin by reading into buffer 1. 


IERR = IREADC256,BUFFERC1,1),0, INCHN) 

IF CIERR .GE. 0) GO TO 20 ! Successful read 

IF CIERR .EQ@. €-1)) GO TO 150 § EOF means all done 
GO TO 100 ! Read error 


Initialize block numbers and flags. 
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PR1504.FOR ~ BLOCK = 1 ! Initialize block number & 
(continued) INPTR = 2 input buffer number & 
OUTPTR = 1 output buffer number 


Loop: Wait for input to complete, compute, 
output. 


IF CIWAITCINCHN) .NE. 02 GO TO 100 ! Error on read 


Read next block into input buffer. 


gaanaownddndaan 


IERR = IREADC256,BUFFERC1,INPTR),BLOCK, INCHN) 
IF CIERR .LT. €-1)) GO TO 100 ! Error on read 


Perform computation on output buffer while read is 
in progress. Computation consists of dividing each 
element of the buffer by 2 (scaling operation). 
Normally, a subroutine would be called to do the 
computation. 


wooanondanaoaana 


DO 60 I#1,256 
BUFFERCI ,OUTPTR)=BUFFERCI ,QUTPTR)I/2 
CONTINUE 


Write out buffer on which computations have just 
completed. 


IF CIWRITEC256,BUFFERC1,OUTPTR),BLOCK-1,QOUTCHN) .LT. 0) 
GO TO 101 ! Error on write 


Check if last read resulted in EOF. 

IF CIERR .EQ@. €-1)) GO TO 150 ! Copy completed. 
Otherwise, switch buffers and advance block number. 
ITMP = INPTR 

INPTR = QUTPTR 

OQUTPTR = ITMP 


BLOCK = BLOCK+1 
GO TO 30 


ERROR ROUTINES 


CALL PRINTC’Read error, copy aborted’) 
GO TO 140 

CALL PRINTC’Write error, copy aborted’) 
CMPRTN = .TRUE. 

RETURN 
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PR1504.FOR 
(continued) Wait for last output to complete and return. 


IF CIWAITCQUTCHN) .NE. 0) GO TO 101 
CMPRTN = .FALSE. 

RETURN 

END 

SUBROUTINE CLSCHN 


Close files. 


INTEGER*2 INCHN,QGUTCHN 

COMMON /CHNNLS/ INCHN,OUTCHN 

CALL CLOSECCINCHN) 

IF CICLOSECOUTCHN) .EQ@. 4) CALL PRINT 
C’Protected output file already exists’) 

RETURN 

END 

SUBROUTINE PRGCHN 


Purge channels. 


INTEGER*2 INCHN,OUTCHN 
COMMON /CHNNLS/ INCHN,OUTCHN 
CALL PURGECINCHN) 

CALL PURGE COUTCHN) 

RETURN 

END 


Event-driven I/O Requests 
The formats of event-driven I/O requests for MACRO-11 are: 


-READC - area,chan,buff,went,crtn,blk 
.WRITC _ area,chan,buff,went,crtn,blk 
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Figure 53, 
Flowchart for Multiple Buffering with Separate Input 
and Output Buffers 


READ INTO BUFFER “A” 


FLAG “A” AS INPUT BUFFER 
AND “B” AS OUTPUT BUFFER 
OF THE “COMPUTATION PAIR" 


FLAG "C’ AS INPUT BUFFER 
AND “D” AS OUTPUT BUFFER 
OF THE “I/O PAIR” 


WAIT ON INPUT CHANNEL 
READ INTO INPUT 
BUFFER OF “I/O PAIR” 


COMPUTE, FROM INPUT 
BUFFER OF 
“COMPUTATION PAIR” 
INTO OUTPUT BUFFER OF 
“COMPUTATION PAIR” 


WAIT ON OUTPUT CHANNEL 
WRITE OUTPUT BUFFER 
OF “COMPUTE PAIR” 

SWITCH “COMPUTE 
PAIR” AND “I/O PAIR” 
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In these requests ‘‘crtn’’ is the address of the completion 
routine that is to be run when this I/O transfer completes. 
Other arguments are identical to the other queued I/O re- 
quests. 

The formats of event driven I/O requests in FORTRAN 
IV are: 


IERR = IREADC (went,buff,blk,chan,crtn) 
IERR=IWRITC (went,buff,blk,chan,crtn) 
IERR = IREADF (went,buff,blk,chan,area,crtn) 
IERR = IWRITF (went,buff,blk,chan,area,crtn) 


In these requests, ‘“‘crtn” is the name of the completion 
routine to be run when this I/O transfer completes, and 
“area” is the name of a four-word area you must have in 
your program if you use IREADF or IWRITF. All other ar- 
guments are the same as for the other queued J/O requests. 

Use IREADC and IWRITC if you are using completion 
routines written in MACRO-11. Use IREADF and IWRITF 
if you are using completion routines written in FORTRAN 
IV. If you use IREADF or IWRITF, remember to include the 
area argument. This may be either an array or a variable. 
Do not modify or use this argument again until the com- 
pletion routine has started execution. The USR must not 
swap over the area argument. 

The routine that issues an IREADC, IWRITC, IREADF, 
or IWRITF request must also issue an EXTERNAL state- 
ment for the name of the completion routine(s) being passed 
to any of these requests. 


Completion Routines 


The key to event-driven I/O is the completion routine. 
Completion routines are called as subroutines by the mon- 
itor. When a job issues an event-driven I/O request and that 
request completes, the completion routine for the request 
runs, regardless of the state of the job that issued the orig- 
inal request. 

A completion routine can perform almost any opera- 
tion needed when an I/O transfer completes. It can: 
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e¢ Issue a new I/O request 


e Set a flag indicating completion of the I/O request, for 
use by another routine of the job 


e Check for end-of-file or hardware errors that may 
have occurred during the transfer 


¢ Do limited processing on the input data 


Later in this chapter, we will discuss what completion rou- 
tines cannot do. 

You should try to keep completion routines as short 
as possible. A long completion routine delays execution of 
the main job and may delay execution of other completion 
routines. When possible, have the completion routine set 
some flags, or record a few items of information, but leave 
any heavy computation to the main job. 


Priority Levels and Scheduling 


User-written routines under RT—11 have relative priorities 
that RMON uses when determining which routine to run 
next. In the SJ applications previously discussed, all rou- 
tines within a job have the same priority, and a routine runs 
only if it is called or jumped to by another routine running 
in that job. Under the FB monitor, the routines of the fore- 
ground job have a higher priority than those of the back- 
ground job. Routines in each job run independently of those 
in the other job, except that those in the foreground job can 
interrupt those of the background job. 

When a job starts a completion routine, two priority 
levels exist for that job. The main-line routine or program, 
and any routines that the main line calls or jumps to, are 
said to execute at main level. The completion routine that 
you specify in an event-driven I/O request, and any rou- 
tines that the completion routine may call or jump to, ex- 
ecute at completion level. Any routines executing at com- 
pletion level have a higher priority than the main level of 
the job that issued the I/O request. 
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Scheduling Completion Routines 
under the SJ Monitor 


Under the SJ monitor, a completion routine is called as soon 
as the I/O transfer completes, regardless of what was inter- 
rupted by the I/O completion (one completion routine can 
interrupt another). This arrangement is called a system of 
nested completion routines. One could say that completion 
routines under the SJ monitor are executed: last in—first out 
(LIFO). 

If two or more outstanding event-driven I/O requests 
are using the same completion routine, the LIFO method 
used by the SJ monitor can cause that routine to be called 
again before it has returned and errors can occur. Figure 54 
shows how this situation can occur. As you study the fig- 
ure, please refer to the following notes which describe the 
sequence of events. 


Main-level routine issues 
event-driven request with 
CR as completion routine. 


Main-level routine issues 
second event-driven re- 
quest with CR as comple- 
tion routine. 


First I/O request com- 
pletes. 


Second I/O request com- 
pletes. 


Second call of CR com- 
pletes, returns. 


First call of CR completes, 
returns. 


Transfer is queued to. 
device handler. 


Transfer is queued to 
device handler. 


CR is called (first call). 


CR is called (second 
call, reentrance occurs 
at this point and errors 
can occur). 


First call of CR contin- 
ues at the point at 
which it was inter- 
rupted. 


Main-level routine 
continues at the point 
at which it was inter- 
rupted. 
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Figure 54. 
Reentrance of a Completion Routine under the SJ Monitor 


MAIN LEVEL 


EVENTS FLOW OF 
(SEE NOTES) CONTROL 


Reentrance (as shown in figure 54) can cause execu- 
tion errors if the reentered routine has not been written to 
allow for reentrance. If the second call of the routine (events 
4 and 5) changes the values of any locations set by the first 
call (between event 3 and event 4), then, when control re- 
turns to the first call (event 5), the routine will be operating 
on incorrect data. 

To prevent reentrance-caused errors, you can write 
MACRO-—11 reentrant completion routines that return the 
same values as those on entry. To do this, save on the stack 
the old contents of any locations that are to be changed 
during the course of the routine, and restore them before 
returning from the routine. Another method is to use stack 
storage only. 

FORTRAN IV routines cannot be made reentrant. If your 
completion routine is not reentrant, you must make sure that 
only one request for any given completion routine is out- 
standing at any given time. You can use a flag that is-set 
while.the completion routine is outstanding. Check the flag 
before issuing the I/O request. If the flag is clear, set it and 
issue the request. (If it is not clear, take any appropriate ac- 
tion.) The completion routine should clear the flag as its 
last action before returning. 
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Scheduling Completion Routines 
under the FB Monitor 


When an event-driven I/O request completes under the FB 
monitor, the completion routine for the request is inserted 
into a completion queue, which is a list of completion rou- 
tines to be run by the scheduler of RMON, according to the 
scheduling algorithm. 

The completion queue is maintained by RMON using 
a linked list of structures called completion queue ele- 
ments. A completion queue element is the I/O queue ele- 
ment from the I/O request, modified by the RMON before 
being inserted into the completion queue. 

The completion queue for a job is maintained and used 
as a first in—first out (FIFO) queue, so the completion rou- 
tines of each job run sequentially, in the order in which the 
I/O requests completed. Management of a job’s completion 
queue is shared by two parts of RMON—the queue man- 
ager and the scheduler. The queue manager is called by a 
device handler when I/O completes. The queue manager 
changes the I/O queue element to a completion queue ele- 
ment and adds it to the completion queue. The scheduler 
is called when the system may need to shift execution from 
one priority level to another (for example, when a level be- 
comes blocked or unblocked, or when a completion rou- 
tine completes). The scheduler calls the completion rou- 
tine as a subroutine. 

Figure 55 shows the FIFO scheduling of completion 
routines under the FB monitor, including the functions of 
the queue manager and the scheduler. This figure shows the 
scheduling of completion routines for an event-driven I/O 
request that completes while another completion routine is 
running on the same job. Completion routines cannot in- 
terrupt one another under the FB monitor, as they can un- 
der the SJ monitor. As you study figure 55, read the follow- 
ing notes which describe the events shown in the figure. 


1 Main-level routine issues Transfer is queued to 
event-driven request with device handler. 
CR1 as completion rou- 
tine. 


166 Programming with RT—11 


2  Main-level routine issues | Transfer is queued to 
event-driven request with device handler. 
CR2 as completion rou- 
tine. 

3 ~~ First request completes. Device handler in- 


forms queue manager 
(part of RMON) of I/O 
completion. 


4 Queue manager inserts 
completion queue element 
for CR1 into completion 
queue. 


5 Scheduler recognizes out- CR1 is called. 
standing completion rou- 
tine CR1. 


6 Second I/O request com- Device handler in- 
pletes. forms queue manager 
of I/O completion. 


Figure 55. 
FIFO Scheduling of Completion Routines under the FB Monitor 


MAIN LEVEL 
6. 
EVENTS FLOW OF 
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Queue manager inserts 
queue element into com- 
pletion queue; recognizes 
that a completion routine 
(CR1) is in progress. 


CR1 completes. 


Scheduler recognizes an- 
other outstanding comple- 
tion routine, CR2. 


CR2 completes. 


Scheduler recognizes that 
there are no more comple- 
tion routines outstanding. 


Control returns to 
CR1. 


Control passes to 
scheduler. 


CR2 is called. 


Control passes to 
scheduler. 


Control returns to 
main level. 


In figure 55, there are two completion queues, one for 
each job. With two jobs active under the FB monitor, there 
are four possible priority levels at which a user-written 
routine may execute. These are shown in table 15. All 
background routines have lower priority than any fore- 
ground routine. Background completion level is at a lower 


priority than foreground main level. 


A job can become blocked either at main level or at 
completion level. Even if the main level is blocked, its 
completion routines are allowed to run; however, the re- 


Table 15. 


Priority Levels in a Foreground/Background Monitor 


Job 


Foreground 


System jobs 
(1 to 6) 


Background 


Level 


Foreground completion 


Foreground main 


System job n completion 


System job n main 


Background completion 


Background main 


Priority 


Highest 


Lowest 
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verse is not true. If a job becomes blocked at completion 
level, RMON does not allow that job’s main level to run. 
This assures that once a completion routine has started to 
execute, the main level does not run again until the com- 
pletion routine has completed. In this way you are assured 
that the main level of a job never executes while some 
completion routine is performing operations. 

With the single exception that, if its completion level 
is blocked, the main level of a job is not allowed to run, 
RMON always runs the highest priority level that is not 
blocked. RMON may shift control from one level to an- 
other when any of a number of events occur, including: 


¢ The current executing routine issues a programmed 
request that causes the routine to become blocked. 


¢ A new completion routine is queued at a priority 
level higher than the current executing routine. 


¢ A completion routine returns, and there are no other 
completion routines at that level. 


e A routine at a higher priority than the current execut- 
ing routine becomes unblocked. 


¢ The current executing job exits or is aborted. 


Any of these events may start an operation of RMON 
known as a scheduling pass. In this operation, RMON ex- 
amines the blocking conditions of jobs (in decreasing order 
of priority), identifies the highest priority level that can be 
run, and executes that level. Because the FB scheduler se- 
rializes the execution of completion routines, there is no 
chance of a routine being reentered under the FB monitor. 


Conventions for Writing Completion Routines 


Certain RT—11 conventions govern the writing of a com- 
pletion routine. n MACRO-11 these conventions are: 


¢ A completion routine is always called with a JSR PC 
and is returned with an RTS PC. 
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¢ Before calling a completion routine, RMON puts the 
value of the channel status word (CSW) for this re- 
quest in RO, and the channel number of the request 
in R1. Your completion routine should check the 
CSW for indications of hardware error (bit 0) or end- 
of-file (bit 13). It can use the channel number to dis- 
tinguish I/O requests if the same completion routine 
is used on more than one channel. 


e A routine can use RO and R1. Any other registers 
must be saved and restored. 


In FORTRAN IV the conventions are: 


¢ A completion routine is defined using a SUBROU- 
TINE statement. Use RETURN to end execution of 
the routine. 


¢ This completion routine may have up to two argu- 
ments, of INTEGER data type. The SUBROUTINE 
statement can define up to two arguments. RMON 
puts the value of the channel status word (CSW) in 
the first argument, and the channel number of the re- 
quest in the second. Your completion routine should 
check the CSW for indications of hardware error or 
end-of-file. It can use the channel number to distin- 
guish I/O requests if the same routine is used on 
more than one channel. 


e Remember that the FORTRAN IV routine that issues 
IREADC, IWRITC, IREADF, or IWRITF must declare 
the names of any completion routines in an EXTER- 
NAL statement. 


e A completion routine for IREADC or IWRITC, written 
in MACRO—11, must obey all conventions that apply 
to assembly language completion routines. 


Restrictions on Completion Routines 


RT-11 places certain restrictions on completion routines 
because they execute independent of the main level. Exe- 
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cution errors may occur if you do not follow these restric- 
tions. The following restrictions apply to both MACRO-11 
and FORTRAN IV: 


A completion routine must not reside in the area into 
which the USR swaps. If the main level issues a re- 
quest that needs the USR, and I/O completes while 
the USR is in memory, control does not transfer to 
the completion routine (which is swapped out) but to 
some part of the USR. USR swapping is discussed in 
chapter 18, ‘‘Using Memory.” 


A completion routine must not execute any request 
that needs the USR, as the USR is not reentrant. 


Under the SJ monitor, either a completion routine 
must be reentrant, or you must make sure that only 
one request using that completion routine is active at 
any given time. 


Any routine callable from both main level and com- 
pletion level must be reentrant. 


The following restrictions apply to FORTRAN IV programs 
only: 


When using OTS I/O (FORTRAN IV READ and 
WRITE statements), the first I/O statement to any spe- 
cific logical unit number, or the OPEN statement, 
causes the OTS to execute a programmed request that 
needs the USR. Therefore, neither of these types of 
statement should appear in a completion routine. 
Also, a completion routine should not contain a 
CLOSE statement or a call to the CLOSE subroutine. 


Do not call IGETC or IFREEC from a completion 
routine. 


The section of the OTS that supports FORTRAN IV 
subprogram calls and returns is not reentrant. This 
means that no subroutine or function written in FOR- 
TRAN IV should be callable both from main and 


Chapter15 Using Nonsynchronous Queued Input/Output 171 


from completion level. It also means that under the 
SJ monitor, only one completion routine written in 
FORTRAN IV should be outstanding at any given 
time. 


Applications for Event-driven I/O 


Event-driven I/O is most useful when you are working with 
devices whose data rates are in some way random. Let us 
look at some examples. 

Suppose that your program performs I/O on a number 
of channels and you have no way of knowing which chan- 
nel will be the first to complete. Asynchronous I/O is of no 
use here because you cannot select any one channel to wait 
on, as a different channel may complete first. Instead, you 
can use a completion routine to indicate completion on any 
channel when it occurs, and to inform the main line. 

You can use event-driven I/O to overlap input opera- 
tions on different channels only if those channels use dif- 
ferent device handlers, or if the handler queues requests 
internally. Otherwise, the I/O system serializes requests to 
the handler. 

Now, consider a program handling input from a de- 
vice that has a high, but variable, data rate. To make sure 
that no data is lost because of a delay in issuing a new I/O 
request after the old one completes, you must have an in- 
put request outstanding on the channel at all times. You 
can implement this by using event-driven requests and 
having the completion routine issue a new input request as 
its first action. 

One problem presented by a device with high but 
variable data rate, is that the input data rate may temporar- 
ily exceed that of the computation routines. If this occurs, 
you may need a carefully controlled system of multiple 
buffers to store the input data until the data rate drops and 
the computation routines at main level have a chance to 
process the data. 

A similar condition is one in which the rate of input 
and/or computation temporarily exceeds the rate of the 
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output device. If there is more data to be output, this too, 
would need multiple buffers and a completion routine that 
issues a new output request as soon as the old one 
completes. 

Finally, event-driven I/O is the only choice if the main 
level of your program has any operation it must perform 
continuously while waiting for I/O completion. For exam- 
ple, your program may be doing real-time process control 
using some set of control parameters. These parameters may 
change as a result of some input, but your program cannot 
issue synchronous requests, or use WAIT to wait for the in- 
put because it would then stop executing its control pro- 
cedure. By using event-driven I/O, the main level can con- 
tinue control using the old parameters, until new ones come 
in. 

The applications described above usually apply to real- 
time I/O devices instead of the standard peripheral devices 
supported by RT-11. In fact, the major application of event- 
driven I/O is to support nonstandard devices. 


Practice . Write a program that: 
15—1 


Reads a data file from a disk one block at a time. 


Finds the maximum value in the block, interpret- 
ing each word as a signed integer. 


Writes a block to an output file that contains the 


difference between each word in the input data 
block, and the maximum of that block. 


Use a multiple-buffering algorithm to give maximum 
throughput. For more practice designing your own al- 
gorithm, you can use a triple-buffered algorithm in or- 
der for input, computation, and output to all proceed 
concurrently. 
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Practice For each programming problem described below, indicate 
15—2 which mode of I/O (synchronous, asynchronous, or event- 
driven) should be used. Justify your answer. In each prob- 
lem, assume that standard device handlers are available for 
each of the devices mentioned. 


1. Your program is engaged in process control. It is re- 
sponsible for maintaining the temperature and pres- 
sure of a system within certain preset limits. A pres- 
sure sensing device PS:, and a temperature sensing 
device TS:, provide input data when the pressure or 
temperature changes. If either value goes past its pre- 
sent limit, your program is to respond by sending new 
control parameters to a control device CL:. What mode 


would you use for the input requests for devices PS: 
and TS:? 


Your RT-—11 system receives data from an input device 
IN:. It must assemble this data into packets that are to 
be sent across a communications line to another pro- 
cessor, which appears to your program as a device PR:. 
The data rate of IN: is expected to be very close to, but 
will not exceed that of PR:. Which I/O mode would 
you use? 


Your program generates reports. It takes input from a 
file on a high-speed disk, formats it, and prints the for- 
matted report on the terminal. Which I/O mode would 
you use? 
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A job can be waiting for an I/O operation to complete for 
much of its time, even when using nonsynchronous I/O, 
because peripheral devices operate much more slowly than 
the processor. Under the Single Job monitor, the CPU is idle 
during these waiting periods. Under the Foreground/ 
Background monitor, however, you can make more effi- 
cient use of your processor by running one (background) 
job when a second (foreground) job is waiting for some ex- 
ternal event. With the proper understanding of RT—11 job 
control, you can write application programs in ways that 
best utilize the foreground/background capabilities of the 
system. 

This chapter explains the basic concepts of RT—11 job 
management and describes the programmed requests that 
can increase your control over job execution under the 
Foreground/Background monitor.: The MACRO-11 re- 
quests discussed include: .SPND, .RSUM, .CNTXSW, .WAIT, 
and .TWAIT. The FORTRAN IV requests discussed are © 
SUSPND and RESUME. 

When you have completed this chapter, you will be 
able to write code to block a job until completion of a spe- 
cific I/O request. You will also learn to design an applica- 
tion system, separating tasks for foreground and_ back- 
ground jobs in a way that maximizes system throughput. 
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Scheduling 


When you issue a KMON command to run a job, that job 
becomes active. It stays active until it exits, or is aborted 
by an error or (ctruc). The SJ monitor supports only one ac- 
tive job. A standard Foreground/Background monitor sup- 
ports two. 

The foreground/background scheduling concepts dis- 
cussed in this chapter are the same for both Foreground/ 
Background and Extended Memory monitors, so the term 
‘‘foreground/background”’ is used to apply to both in this 
chapter. 

The system job option, available through system gen- 
eration, enables a Foreground/Background monitor to sup- 
port up to six system jobs in addition to the foreground and 
background jobs. 

Regardless of how many jobs are active under a mon- 
itor, only one can use the CPU at a time because the CPU 
can execute only one instruction at a time. The resident 
monitor RMON determines which job is given the use of 
the CPU. The process of allocating the CPU among active 
jobs is called scheduling. The three basic concepts of 
scheduling under the RT—11 Foreground/Background mon- 
itors are: 


1. Priority. Each job has a fixed priority, which RMON 
uses to determine which job will get the CPU. RMON 
always runs (gives use of the CPU to) the highest 
priority job that is capable of running. 


2. Blocking. When a job is not able to run because it 
needs some external event, such as completion of a 
read request, it is said to be blocked. RMON recog- 
nizes when a job is blocked and allows a lower prior- 
ity job to run. 


3. Context. To help keep track of active jobs, RMON 
keeps important data about each job. This data is the 
context in which the job is said to run. When RMON 
transfers use of the CPU from one job to another, it 
first performs an operation known as a context 
switch. 


Priorities 


Blocking 
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The next three sections explain these concepts in more 
detail. 


Under a Foreground/Background monitor, every job has a 
software priority that is fixed at the time that the job is in- 
itiated. The background job has the lowest priority, and the 
foreground job has the highest. If the monitor has system 
job support, all system jobs have priorities between those 
of the background and foreground jobs. 

This system of software priorities is used by RMON to 
determine which job to run. These priorities are different 
from the hardware priorities used for servicing interrupts 
on PDP—11 computers. 

If a job requests completion routines, it can be run at 
two levels: main level and completion level. The comple- 
tion level has a higher priority than the main level (but a 
lower priority than the main level of the next higher prior- 
ity job). This priority structure is shown in table 15. 

The foreground and background job slots are for ap- 
plication and utility programs. The system jobs slots are re- 
served for special programs provided by Digital. The pro- 
grams currently provided with RT—11 are the device queue 
package, error log programs, transparent spooler, and vir- 
tual communications program. 


Levels can be in one of two states, blocked or runnable. A 
blocked level is not able to proceed until some condition 
is met. A level not blocked is runnable. Usually RMON 
blocks a job when the job issues a programmed request that 
for some reason cannot be completed immediately. Some 
requests that cannot be completed return an error to the 
program. If the error is fatal, RMON aborts the program. 
Normally RMON blocks a job if there is a delay and aborts 
the program if there is a serious error. RMON unblocks the 
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job when the conditions have changed, and it can com- 
plete the programmed request. Some examples of this type 
of blocking are: 


¢ Terminal I/O requests. The job is blocked if no char- 
acters are available on input, or no space in the 
buffer is available on output. (If bit 6 of the job status 
word is set, the job is not blocked.) 


e Synchronous I/O requests. The job is blocked until 
the transfer is complete. 


e USR requests. If the USR is owned by another job, 
the requesting job is blocked until the USR is avail- 
able again. This situation is discussed in chapter 18, 
“Using Memory.”’ 


¢ I/O requests. If a job issues an I/O request and no 
queue element is available, the job is blocked until a 
queue element is available. 


Some programmed requests can block a job, for example: 


¢ The .WAIT request blocks a job until an I/O channel 
is clear. 


e The .TWAIT request blocks a job for a specified pe- 
riod of time. 


¢ The .SPND request blocks a job until it issues a 
.RSUM to resume. 


The word I.BLOK in the job’s impure area is a flag word 
used to indicate blocking conditions for the job; the bits in- 
dicate what caused the job to be blocked. The only block- 
ing condition not flagged in I.BLOK is blocking because no 
queue element is available; this condition is processed by 
another part of RT—11. Figure 56 shows all the conditions 
flagged by I.BLOK. The bits not used are reserved for future 
use. 

When RT-—11 needs to block a job, it sets a bit in 
I.BLOK. The scheduling routine in RMON uses this word 
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Figure 56. 
Blocking Conditions Flagged by |.BLOK 


_ | BLOK 
14. 13 12 11 10 9 8 6 4 

SEE, WAITING FOR USR 

coe SUSPEND COMMAND 

EXITS WAITING FOR ALL I/O 
TO COMPLETE 

NORUNS NOT RUNNING (COMPLETED 
FOREGROUND OR SYSTEM JOB) 

SPNDS JOB SUSPENDED 

CHNWTS WAITING FOR 1/0 
ON A CHANNEL 

HeENe - WAITING FOR TERMINAL 
OUTPUT BUFFER EMPTY 

TIOWTS WAITING FOR ROOM IN THE 
TERMINAL OUTPUT BUFFER 

TTIWTS 


WAITING FOR TERMINAL 
INPUT 


to check if the job is runnable. Later when the event being 
waited for occurs, the monitor clears the appropriate bit. 

I.BLOK records the blocking of the job’s main level, if 
there are no completion routines queued. When comple- 
tion routines are queued, the main-level blocking bits are 
saved, and I.BLOK records the blocking conditions of the 
completion level. After the last completion routine in a job’s 
completion queue has run, RMON restores the blocking 
conditions of the main level in the I.BLOK word. This means 
that a job’s completion level can run even if the main level 
is blocked. However, if a completion routine becomes 
blocked, both levels of the job are blocked; that is, the main 
level does not run. 

Routines within RMON recognize events that change 
the blocking state of a job and the level at which a job op- 
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erates (main or completion). When they recognize one of 
these changes, they request RMON to run a pass of the 
scheduling routine. RMON examines jobs in order of de- 
creasing priority, starting with the job whose status has 
changed. Figure 57 shows how this scheduling pass runs. 

The result is that RMON runs the highest priority job 
runnable. It also runs a job’s completion routines before it 
runs the main level. The numbered notes (opposite page) 
apply to figure 57. 


Figure 57. 
A Scheduling Pass 
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1 The I.BLOK word is tested. 


2 When RMON switches the job to completion level 
(see note 4), it records this by setting the CMPLT$ bit 
in the job state word ILSTATE in the job’s impure 
area. 


3 A pending completion routine is one that has been 
placed into the completion queue but has not started 
executing. This condition is also recorded in the 
I.STATE word. 


4 Once a job enters completion level, it stays there until 
there are no more completion routines pending. If a 
job is blocked while at completion level, the main 
level is not run. After the last completion routine 
runs, RMON clears the CMPLT$ bit in the LSTATE 
word and a new scheduling pass is started. 


Context Switching 


Context switching occurs when the scheduler, as a result 
of a scheduling pass, starts to execute a job other than the 
one that was running before the pass. Basically, the opera- 
tion saves some information from the outgoing job and re- 
stores some information about the incoming job. 

Context switching can occur after any scheduling pass 
but not necessarily after every scheduling pass. Only 
scheduling passes that change jobs result in a context switch. 
Switching between a job’s main level and its completion 
level does not change jobs and, therefore, does not cause a 
context switch. In general, a context switch occurs when a 
high priority job (the foreground job or a system job) be- 
comes blocked, allowing a lower priority job to run, or when 
a high priority job becomes unblocked, and therefore, in- 
terrupts a lower priority job. 

Certain memory areas and registers contain a job’s. data 
while it is being executed. When a different job starts exe- 
cuting, these areas must contain the new job’s data. When 
a context switch occurs, the old contents of these locations 
are saved on the stack and in the impure area of the out-. 
going job, and the incoming job’s data for these areas is 
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loaded from the incoming job’s stack and impure area. This 
information includes: 


All the general purpose registers (the stack pointer it- 
self is always stored in the job’s impure area) 


The vector for the TRAP instruction 
The system communication area (words 40 to 52) 


If floating point hardware is present, certain registers 
of the FPP 


In a multiterminal monitor, word 56 (fill count and 
character) 


In an extended memory monitor, the BPT and IOT 
vectors, kernel PAR1, and the memory-management 
fault trap vector 


In addition, a MACRO-11 programmer can use the 


.CNTXSW request to specify other locations to be saved 
across a context switch operation. This is normally used for 
jobs that share trap or interrupt vectors. 


Using FB Scheduling Efficiently 


The goal of foreground/background operation is to make 
better use of the CPU, which under some conditions is idle 
for much of its time. Efficient FB scheduling depends on 
the coding of your application programs. If you want to use 
both foreground and background jobs in programming your 
application, the following points will help you determine 
which functions to put into the foreground and which to 
put into the background: 


Your system performance will be best if the highest 
priority job (foreground) is blocked most of the time, 
allowing lower priority jobs to run; and if the lowest 
priority job (background) is using the CPU most of 
the time, thereby taking up the CPU time left over by 


‘the foreground and any system jobs. It is common 


practice to do real-time I/O in the foreground, and 
data analysis in the background. 
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e Ina real-time application, some operations are time 
critical. That is, the program must provide very fast 
response to changes in external conditions. Time-crit- 
ical operations should be placed in the foreground so 
that no higher priority job can take the CPU from the 
program performing a time-critical operation. Opera- 
tions not time-critical are best performed in the back- 
ground. 


e You can run a foreground job and switch from one 
background job to another, however, you cannot 
change foreground jobs without interrupting the 
background job. This is because you run KMON in 
background when you issue the command to run a 
foreground job. The foreground is the best place for 
continuous operations such as monitoring, data col- 
lecting, or process control. ! 


e Short or infrequent operations (such as initialization, 
queries, changes, parameters, or report generation) 
can be put into programs that run as background jobs 
when they are needed. This saves space in the fore- 
ground job. 


Examples of this type of organization include the 
queuing and error-logging systems in RT-—11. Each has a 
single foreground/system job (QUEUE and ERRLOG), which 
runs continuously, and one or more background jobs 
(QUEMAN in the queuing system, and ELINIT and ERR- 
OUT in error logging), which are run only when their op- 
erations are needed. The background jobs run infrequently 
in comparison to foreground or system jobs. 

You should also consider whether you need to use both 
a foreground and background job. CorRext switching takes 
time. How much time depends on the processor and mon- 
itor you are using, and whether your jobs have issued 
-CNTXSW requests. It is usually a few tenths of a millisec- 
ond. Normally your application runs faster if you combine 
all functions into one job than if you use two jobs, because 
there will not be any context switching. There are, how- 
ever, other reasons—such as efficient use of the CPU and 
memory—for separating your application into two jobs. 
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The execution of a foreground job includes periods 
wien the job is blocked and periods when the job is run- 
nable. Each change between blocked and runnable may need 
a context switch. A job with fewer larger periods uses the 
system’ more efficiently than a job with many smaller pe- 
riods because the former needs fewer context switches. 
Therefore, when writing a foreground job, try to organize it 
to minimize the number of context switches. 

- A common mistake in the use of completion routines 
is trying to increase the efficiency of a job by performing 
operations at completion level, and therefore, at a higher 
priority than at main level. This does not always help your 
program and can even slow it down. The FB monitor runs 
completion routines FIFO, so if one completion routine takes 
a long time to run, it delays all the routines following it. 
Keep completion routines as short as possible, doing any 
long processing at the main level. Also, make sure that very 
long processing is done in the background job. 


Waiting for Specific Events 


The synchronous I/O requests, the WAIT request for an I/O 
channel, and the timed wait request (TWAIT) each block a 
job until a specific condition has been met: completion of 
I/O on a channel, or expiration of a time limit. Sometimes 
you want your job to be blocked until some more complex 
condition is met. For example, you may want to: 


¢ Issue a number of I/O requests on a channel, and 
then block your program until a specific request 
(other than the last one) completes. 


¢ Issue a number of I/O requests on different channels, 
and then block your program until any one (or a spe- 
cific combination) of those requests completes. 


e Issue an I/O request, and then block your job until 
either that request completes or a watchdog mark- 
time routine runs. This is discussed in chapter 20, 
“Writing Time-dependent Programs.”’ 
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An example of these techniques is the QUEUE pro- 
gram. It suspends the main level, waiting for a message from 
QUEMAN. At the same time it has a watchdog routine to 
check for (ctrucyctrucy being entered. 

Each of these blocking situations can be implemented 
using completion routines, event-driven I/O requests, and 
mark time requests. To wait for a specified condition, your 
main-level routine can check a flag or some set of flags that 
are to be set by the completion routines, and then loop un- 
til the flags have the values needed. 

This procedure is, in fact, the best way to implement 
a waiting condition under the SJ monitor. It is not, how- 
ever, the best way under the Foreground/Background mon- 
itor, because it does not block the job. A foreground job that 
loops like this uses valuable CPU time, during which a 
background (or system) job might be able to run. 

To allow a job to be blocked until some condition de- 
fined by the programmer is met, the Foreground/ 
Background monitor provides a suspend and resume re- 
quest. To suspend a job, the MACRO-—11 request is: 


.SPND 

To suspend a job, the FORTRAN IV request is: 
CALL SUSPND 

To resume a job, the MACRO-11 request is: 
.RSUM 

To resume a job, the FORTRAN IV request is: 
CALL RESUME 


A suspend request is usually issued from the main level 
of the job. It blocks the job at the main level, but allows 
completion routines to run. A suspend request issued from 
completion level has a different effect. The resume request 
is almost always issued from a completion routine. It un- 
blocks the main level which starts to execute again as soon 
as all processing at completion level has been done. Sus- 
pend and resume requests have the following effects: 
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e A suspend counter is kept for each job in its impure 
area. The initial value of this counter is 0. 


¢ Each suspend request decreases the counter. Each re- 
sume request increases the counter. 


e If the counter is negative, the main level of the job is 
blocked. 


The one exception is when a suspend request issued 
from a completion routine causes the counter to become 
negative. The main level is not immediately blocked; it is 
blocked the next time a suspend request is issued from main 
level. At that time, the counter is equal to —2 and two re- 
sume requests are needed in order to unblock the main level. 

The use of a counter ensures that a program is not sus- 
pended if the completion routine issues the resume request 
before the main level is able to issue its suspend request. 
The suspend request returns immediately to the main level 
because the blocking condition has been cleared in 
advance. 

Use suspend and resume requests with caution if your 
program also uses TWAIT requests. TWAIT is imple- 
mented by RMON using an internal mark time request, a 
suspend request, and a resume request from within RMON’s 
mark time completion routine. Because of this, if your 
completion routines issue one resume request too many, this 
can cause a TWAIT request in the main level to finish too 
soon. 
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Transferring 
Data sy 
Between 
Jobs 


A foreground job and a background job running at the same 
time may be unrelated. For example, an application pro- 
gram runs in the foreground while program development 
takes place in the background. In this case, the Fore- 
ground/Background monitor is being used as a tool to al- 
low the processor to do more than one thing at a time. In 
another instance, the foreground and background jobs may 
have a common application and the two jobs must be able 
to communicate with each other to coordinate their oper- 
ations and swap information. 

This chapter discusses the programmed requests that 
allow your foreground and background jobs to communi- 
cate, either directly through memory or through files on a 
mass storage device. The MACRO-11 programmed re- 
quests discussed in this chapter are: .SDAT, .SDATW, 
SDATC, .MWAIT, .RCVD, .RCVDW, .RCVDC, and .CHCOPY. 
The FORTRAN IV requests discussed are: ISDAT, IS- 
DATW, ISDATC, ISDATF, MWAIT, IRCVD, IRCVDW, 
IRCVDC, IRCVDF, and ICHCPY. 
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When you have completed this chapter, you will be 
able to use the send and receive data requests to copy in- 
formation from one job to another; write a pair of fore- 
ground and background jobs that communicate through a 
shared buffer area; synchronize a foreground and back- 
ground job using synchronous send and receive data re- 
quests; and transfer files between foreground and _ back- 
ground jobs that are running at the same time. 


Communication Through Send 
and Receive Requests 


RT—11 supports three job communication methods: send and 
receive requests, shared buffers, and shared files. Fore- 
ground and background jobs can communicate directly 
through memory using send data and receive data requests, 
which are similar to write and read requests to peripheral 
devices under the queued I/O system. The similarities are 
shown in table 16. The send and receive data requests are 
shown in table 17. 

The word count argument (went) for all the requests 
shown in table 17 must be positive. All other arguments are 
identical to those for the corresponding queued I/O re- 
quests. The MWAIT request blocks the job that issues it until 
all send and receive requests that the job issued are com- 
pleted. It is possible for one job’s MWAIT request to return 


Table 16. 
Similarities between Queued I/O and Communication Requests 


Queued Requests 
Requests to write to a 
channel 


Requests to read from a 
channel 


Three I/O modes 


WAIT request to wait for 
/O on a channel to complete 


Communication Requests 


Requests to send data to 
other job 


Requests to receive data 
from other job 


Same three modes 


MWAIT request to wait until 
message requests complete 
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successfully if the other job has communication requests left. 
MWAIT waits only for completion of the communication 
requests of the job that issued the MWAIT. 


Table 17. 
Send and Receive Data Requests 
MACRO-11 Requests FORTRAN IV Requests 
Synchronous .SDATW area,buff,went IERR= ISDATW (buff,went) 
.RCVDW area,buff,went IERR= IRCVDW (buff, went) 
Asynchronous’ .SDAT area,buff,went IERR= ISDAT (buff,went) 
.RCVD area,buff,went IERR= IRCVD (buff,went) 
.MWAIT CALL MWAIT 


Event-driven .<SDATC area,buff,went,crtn IERR= ISDATC (buff,went,crtn) 
-RCVDC area,buff,went,crtn IERR= IRCVDC (buff,went,crtn) 

IERR= ISDATF (buff,went,area,crtn) 

IERR= IRCVDF (buff,went,area,crtn) 


System Message Handler 


Communication requests are implemented by RMON using 
a pseudo-device handler called the system message han- 
dler. The system message handler is responsible for exe- 
cuting send and receive data requests, which the handler 
receives as if they were queued I/O requests. On FB and XM 
monitors, you can reference the system message handler as 
the MQ: device, open channels through it, and access it us- 
ing queued I/O read and write requests. Communication re- 
quests are controlled in the same way as queued I/O re- 
quests, so every communication request uses an I/O queue 
element from the job issuing the request. Remember this 
when issuing QSET requests at the start of your programs. 

The system message handler matches a send queue 
element from one job with a receive queue element from 
another job. Once such a match is made, information is 
transferred from the sending to the receiving job, and both 
programmed requests (the send and the receive) are re- 
ported as having completed. This procedure sets up two 
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Figure 58. 
Flow of Information through the System 
Message Handler 
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independent paths, similar to channels in the queued I/O 
system. One path handles information sent from fore- 
ground to background, and one goes from background to 
foreground. This flow of information is represented in fig- 
ure 58. 

The system message handler keeps track of commu- 
nication requests by keeping a queue of waiting requests. 
This queue is made up of the I/O queue elements that RMON 
passes to the system message handler. The flowchart in fig- 
ure 59 shows the action of the system message handler when 
it receives a new communication request. The following 
points apply to send and receive requests: 


e Each new send request must be matched by a receive 
request from the other job (and each new receive re- 
quest must be matched by a send request) before it 
can complete. 
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Figure 59. 
System Message Handler Processing a New Request 
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e If a request is received and no matching request is in 
the current queue, the queue element for the new re- 
quest is placed in the queue to wait for a request that 
matches it. 


¢ The queue is a first in—first out (FIFO) one. A search 
for a match for a new request always starts at the 
head of the queue. If it is necessary to add a new 
queue element, it is added at the end of the queue. 


e If one job issues both a send and a receive, these re- 
quests may not be completed in the same order in 
which they were issued. The order of completion de- 
pends on the order in which the other job issues its 
requests. This is different from standard queued I/O 
requests. Queued I/O requests to a device handler are 
always completed in the order they were issued. 


Because of the way that send and receive requests are 
matched by the system message handler, the I/O mode of 
the send need not match that of the receive. Thus, you can 
use an event-driven send from the foreground and a syn- 
chronous receive from the background. | 


Send and Receive Buffers 


Each send request and each receive request specify a buffer 
within the job that issued the request. Data is copied from 
the sending .job’s buffer (send buffer) into the receiving job’s 
buffer (receive buffer). 

Each communication request also specifies a word 
count, which is the number of words it expects to be copied. 
In the send request, the word count should equal the num- 
ber of words in the send buffer. The word count of the re- 
ceive request should match that of the sending job. They 
may not match if there is an error. The receiving job is ca- 
pable of checking for this type of error, for the message 
handler always passes the sending job’s word count to the 
receiving job, in the first word of the receive buffer. 
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The first word of the receive buffer is used for the copy 
of the sending job’s word count, so you should always make 
your receive buffer one word larger than the receive word 
count. This is very important. Otherwise the data in the 
word immediately after the receive buffer is destroyed when 
the information is copied from the sending job. 

The following figures show how the results of a send 
request and a receive request differ according to the rela- 
tive sizes of the send and receive word counts. Figure 60 
shows the result if the send and receive word counts are 
equal. Figure 61 shows the result if the send count is larger 
than the receive count. Figure 62 shows the result if the re- 
ceive word count is larger. In each figure, the diagonal 
shading represents the words copied from the send buffer 
to the receive buffer. 

Remember that it is up to the receiving job to compare 
the requested receive word count with the send word count 
(found in the first word of the receive buffer) and take ap- 
propriate action if they are different. The action to be taken 
depends on your application. 


Figure 60. 
Send Word Count Equal to Receive Word Count 
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Figure 61. 
Send Word Count Greater Than Receive Word Count 
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Figure 62. 
Send Word Count Less Than Receive Word Count 
RECEIVE BUFFER 
SEND BUFFER 
WORD 
COUNT WORD 
OF SEND COUNT 
REQUEST 
OF 
RECEIVE 
REQUEST 


RESULTS: 


e ALL OF THE SEND BUFFER IS COPIED, BUT 
e PART OF THE RECEIVE BUFFER IS MEANINGLESS 


Chapter17 Transferring Data Between Jobs 197 


Communication Through Shared Buffers 


When the amount of information to be transmitted be- 
tween jobs is more than a few words, it may be better to 
share a common data buffer than to copy all the data from 
one job to the other. 

- Copying the buffer with send and receive requests is 
the more direct of the two options and, for small amounts 
of information, is usually the better choice. Using a shared 
buffer requires more careful planning and complex pro- 
gramming, but there can be significant benefits to using a 
shared buffer. To set up a shared buffer, you use a proce- 
dure like the following: 


1. One job must reserve space for the buffer that is to be 
shared. You can reserve space at compilation or as- 
sembly time by defining a buffer or array. There are 
also methods to reserve more buffer space at run time 
(discussed in chapter 18, ‘‘“Using Memory’’). 


2. The job that reserved the shared buffer uses a send 
request to send a message to the other job. The mes- 
sage contains the address of the buffer and may also 
contain its length. 


A FORTRAN IV program that uses a variable or an 
array for the buffer can find out the address of that 
storage location by using the SYSLIB routine IADDR. 


3. The other job issues a receive request for the message 
in order to find out the address (and length) of the 
buffer that is to be shared. 


MACRO-11 programs can directly access the shared 
buffer. FORTRAN IV programs have to use routines like 
IPEEK and IPOKE in order to use the buffer because the re- 
ceiving routine does not have a variable name for the buffer 
itself, only for a location that contains the address of the 
buffer. 

Another way of gaining access to the buffer is to use 
the MACRO—11 function INDIR. INDIR acts as an interme- 
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diary between two FORTRAN IV routines. It allows the 
calling routine to pass arguments in an indirect manner. 
Instead of giving the name of the variable to be passed, the 
routine’s CALL statement may give the name of a variable 
that contains the address of the value to be passed. Many 
levels of indirection are allowed. The form of the statement 
is: 


Call Indir (Proc, Mode1, Arg1, Mode2, Arg2, .. .) 
or 
X=Indir (Proc, Mode1, Arg1, Mode2, Arg2, .. .) 


“PROC” must be declared as external in the routine calling 
INDIR. For each argument, “MODE” is the number of lev- 
els of indirection. MODE=0 is equivalent to a direct call. 
The program (INDIR.MAC), which follows, shows a MA- 
CRO-11 function that passes arguments to FORTRAN IV 
routines. 

FORTRAN IV programs can use INDIR to interpret ad- 
dresses when calling subroutines. For instance, if the ad- 
dress of an array is in the INTEGER*2 variable IPTER, you 
can call a subroutine, and pass the array as an argument. 


EXAMPLE | 


© eal INDIRCSUBA, 4, IPTER, 0, Nur 


ee SUBACARRAY, iva 
SSS ARRAYC10) ae Oe 
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INDIR. MAC -TITLE INDIRECT FORTRAN CALLS 


This routine may be called by the PROC routine or 
any of its routines. 


MOV CRS)+,R0 ;Load number of arguments 
MOV RO,R1 ;Copy number of arguments 
DEC R1 ;Forget about PROC as arg 
ASR R1 3/2 to remove MODEs 
ASL RO sAdvance to end of 
ADD RS,RO ; argument list 
MOV CRS)+,R4 sLoad PROC routine addr 
MOV SP ,SAVESP ;Save stack pointer 
MOV -CRO),R2 sLoad ARGN address 
MOV @-CRO),R3 sLoad MODEN value 
BEQ 3$ sBranch if MODE = 0 
MOV CR2),R2 sChase indirection 
DEC R3 ;Decrement mode 
BNE 2$ sBranch if MODE <> 0 
MOV R2,-CSP) ;Push argument onto stack 
CMP RO,RS 3All arguments processed? 
BNE 1$ sBranch if not 
MoV R1,-CSP) ;Push number of argument 
MOV SP,RS s;Load argument block ptr 
MOV SAVESP,-CSP) ;Save saved stack ptr 
CALL CR4) ;Call the PROC routine 
Mov CSP)+,SP - gRestore original stack 
RETURN sReturn to caller 
? 
; NOTE: Value returned by INDIR is the value returned by 
; the PROC routine since no registers are modified 
7 upon return from PROC. 


? 
SAVESP: .BLKW 1 ;Saved stack pointer 
-END 


Benefits of Using Shared Buffers 


When you want to transmit information between jobs, the 
benefits of using a shared buffer, instead of send and re- 
ceive requests include the following: 


¢ One copy of the information takes up less memory 
then two copies. 
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¢ Execution can be faster because the data does not 
have to be copied. 


¢ Each job has continuously updated information from 
the other job. The use of a shared buffer, which does 
not need repeated sends or receives, can increase 
program speed and accuracy. 


Disadvantages of Using Shared Buffers 


The disadvantage of using shared buffers to communicate 
between jobs is that programs are harder to write and de- 
bug. For example: 


¢« The two jobs must be synchronized so that they do 
not access the buffer at the same time. 


¢ The job that receives the buffer address might modify 
a location outside the buffer and destroy the first job. 


Restrictions on the Use of Shared Buffers 


There are two restrictions when using shared buffers: 


¢ The second job may not use the shared buffer for I/O, 
in a CDFN or QSET request, or other operation lim- 
ited to addresses within the job’s own memory space. 


¢ Under the XM monitor, a shared buffer must be in 
memory (below 28 Kwords) and both jobs must be 
privileged. 


Synchronizing Buffer Access 


In a coordinated foreground/background system, one job may 
need to know when the other job has started or completed 
some operation. This calls for communication between the 
two jobs, in the form of: | 
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¢ Queries, where job A says to job B: “Send me a mes- 
sage when you have done operation X”’ 


e Status reports, where job B says to job A: “‘I have 
completed operation X”’ 


If job A needs the results of the action taken by job B, 
it should block itself by issuing a synchronous commu- 
nication request (either send or receive). This blocks job A 
and also sets up the condition for removing the block. The 
effect is that job A says to job B: ‘‘Wake me up when you 
are ready.” Job B then must issue the appropriate request 
(receive or send) when it has completed the specified task. 

The content of the buffers used in these send and re- 
ceive requests may not be important. The execution of the 
requests may be enough to indicate: ‘‘Wake me up when 
you are ready,” or ‘‘Wake up! I am ready.” In this example 
the send buffer can be a single word containing a zero. 

The contents of the send buffer can be used to trans- 
mit additional information, such as whether job B com- 
pleted its task successfully, or where the results are located 
in the buffer. ; 

If the job that needs the results can do other work while 
waiting, use a nonsynchronous communication request. 
Then at a later time this job can use M“WAIT to wait for the 
request to complete. It can also check flags set by a com- 
pletion routine or suspend itself until resumed by a com- 
pletion routine. 

If you want a foreground job to receive a message from 
the background job, you must make sure that the fore- 
ground job becomes blocked, to allow the background job 
time to run. Do this either by using synchronous requests, 
or asynchronous requests and MWAIT, or by suspending a 
job until it is resumed by a completion routine. 


Communication Through Files 


Communication using a file is slower than using send and 
receive requests or shared buffers because of the device ac- 
cess time. However, two benefits of file communication are: 
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more information can be stored in a file than in memory 
and a file leaves a permanent record of the information for 
future use. 

If two jobs each have a channel open to the same file, 
both can do J/O to that file. Both jobs’ requests are queued 
to the device handler, as follows: 


e A device handler services only one I/O request at a 
time. Once a handler starts to execute an I/O request, 
it completes that request before it starts on any new 
request. For example, if a handler is servicing an I/O 
request from the background job and a new request 
comes in from the foreground job, the handler com- 
pletes the background job’s request before starting to 
work on the foreground job’s request. 


e All requests for a handler, except for the one cur- 
rently being executed, are queued in order of job 
priority. The requests for the foreground job are first, 
then those of the system jobs, and then the requests 
for the background job. 


¢ Within each job’s section the queue is FIFO. 


Jobs must be synchronized if both modify a shared file. 
Consider an example where the background job reads a block 
from a file, changes a few words in that block, and then re- 
writes the block. After the background job reads that block 
and before it writes the block back, the foreground could 
run and make a change in the block. If the background did 
not know about the foreground’s change, it would write its 
block out, writing over the changes made by the fore- 
ground. You prevent this condition in shared files in the 
same way you prevent it in shared buffers—by setting up a 
system of shared flags or send and receive requests to syn- 
chronize the jobs’ execution. 

Sharing a file is simple if the file was created before 
both jobs are run. Each job needs only to issue a LOOKUP 
request to the file. If two jobs create a file to share, then one 
job must create the file using an ENTER request and tell the 
second job the channel number it is using. The second job 
has to issue a channel copy request. This request can also 
be used if the first job has gained access to the file with an 
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ENTER request. All that is needed to copy a channel to the 
second job is for the first job to have that channel open. For 
MACRO-—11 the channel copy request is: 


.CHCOPY _area,chan,ochan 
For FQRTRAN IV the request is: 
IERR = ICHCPY (chan,ochan) 


In these requests, ‘‘chan”’ is the channel number to be used 
by the job copying the channel, and ‘‘ochan”’ is the chan- 
nel number being used by the job that first opened the file. 

The effect of this request is to copy one job’s channel 
table for this file into the channel table of the other job. 
When this request has been executed, both the copying job 
and the job that first opened the file can access the file. There 
are only two significant differences between the privileges 
of the two jobs: 


1. In the copying job’s channel status word, the write- 
to-directory bit (bit 7) is always clear. So, a CLOSE 
request from the copying job does not make this file 
permanent if it was opened with an ENTER. Only the 
job that created the file can make it permanent. 


2. If the file is opened with an ENTER request, the 
copying job can reference it only up to the highest 
block that had been written to by the entering job at 
the time that the channel copy was performed. The 
copying job cannot read from or write to any blocks 
past that limit. 


One way around this problem is for the entering job 
to write to the last block of the tentative file. This 
saves all blocks when the file is closed, and allows 
both jobs access to all blocks of the file. 


Coordinated Foreground/Background Systems 


The error-logging system and the queuing system are co- 
ordinated foreground/background systems. Each uses both 
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Error Logging 


Queuing System 
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communication requests and channel copying to commu- 


_nicate. Short descriptions of the operation of these systems 


are given here as examples of how these requests can be 
used. 


The error-logging system has two background jobs (ELINIT 
and ERROUT), a foreground job (ERRLOG), and a data file 
(ERRLOG.DAT). ELINIT is responsible for finding (using 
LOOKUP) or creating (using ENTER) ERRLOG.DAT. ELINIT 
opens a channel to ERRLOG.DAT. If ELINIT creates a new 
file, it writes to the last block of the file, saving the com- 
plete length of the tentative file. It closes the tentative file 
to make sure that it is made permanent, then reopens the 
file with LOOKUP. It sends ERRLOG some control infor- 
mation about the file and the system configuration. 

One of the first things that ERRLOG does is issue a 
-RCVDW, which blocks ERRLOG until ELINIT issues its send 
request containing the control information. ERRLOG copies 
ELINIT’s channel to ERRLOG.DAT, issues a .RCVDC for a 
message from ERROUT, and .SPND to suspend itself. 
ERRLOG can become unblocked either by the completion 
routine from the .RCVDC, or from a special routine called 
from device handlers to report error-logging data. When 
ERRLOG becomes unblocked, it writes data to ERRLOG.DAT 
using the channel that it copied from ELINIT, and then 
suspends itself again. ERROUT executes a send data re- 
quest to ERRLOG to ask it to write out the last of its data 
to ERRLOG.DAT. Then ERROUT opens its own channel to 
the file and creates a report based on the data in the file. 


In the queuing system, a foreground job QUEUE opens a 
data file SY:QUFILE.WRK. This file is opened using 
LOOKUP or ENTER and is used to keep track of file trans- 
fer requests for QUEUE. When QUEUE completes one re- 
quested transfer, it deletes the entry for that transfer in the 
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list in SY:QUFILE.WRK, and starts up the next operation. 
New requests are added to the queue as a result of mes- 
sages sent from the background job QUEMAN. QUEUE’s 
main level has three major functions. It processes: 


¢ Requests from QUEMAN. 


¢ The completion of one transfer and the starting of an- 
other. 


e Clean-up operations if QUEUE is aborted. QUEUE in- 
hibits normal (crravc) action and sets up a mark time 
completion routine to run at regular intervals, which 
checks for double (ctruc). 


The main level of QUEUE uses a .RCVDC request to 
check for messages from QUEMAN, .READCs and .WRITCs 
to do I/O, and .MRKT to set up the completion routine to 
look for (ctrucy. Then the main level suspends itself, leaving 
the completion routines to issue the resume request. When 
the main level becomes unblocked, it checks to see which 
completion routine unblocked it, performs the necessary 
task, reissues any needed communication or I/O request, and 
blocks itself again. 

QUEMAN’s main job is to take requests from the user, 
translate them into messages, and send them to QUEUE. One 
request that QUEMAN handles on its own, however, is a 
request to look at the status of current requests in the queue. 
To do this, QUEMAN copies QUEUE’s channel to 
SY:QUFILE.WRK and reads from the file directly. 


This practice requires a Foreground/Background monitor. 
You can write the programs in MACRO-11 or FORTRAN 
IV. If you use FORTRAN IV, the MACRO-11 function IN- 
DIR is shown in the program (INDIR.MAC) presented earlier 
in this chapter. 


1. Write a foreground job and a background job such that: 


a. The foreground accepts a string of characters from 
the terminal. 
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The foreground sends a buffer containing that 
string of characters, to the background. 


The background reverses the order of the charac- 
ters in the string, and then sends a buffer contain- 
ing the reversed string to the foreground. 


The foreground then prints out the reversed string, 
and returns to step a. 


Write the above program using a shared buffer instead 
of copying the strings from one job to the other. 


Modify the programs in step 1. so that: 


a. The foreground writes the original string to block 0 
of a file that it creates using ENTER. 


The foreground sends to the background the chan- 
nel number on which that file is open. 


The background copies the channel from the fore- 
ground, reads the string from block 0, reverses the 
string, and writes the reversed string to block 1 of 
the file. 


The foreground reads block 1 of the file and types 
out the reversed string. 


The program leaves the file permanent when the 
foreground program exits. 


References 


RT—11 Programmer’s Reference Manual. Chapters 2 and 3 dis- 
cuss the channel copy requests for MACRO-11 and FORTRAN 
IV users. 


RT-—11 Software Support Manual. Chapter 4 provides informa- 
tion on the operation of programs sharing buffers under the XM 
monitor. 
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Using 
Memory 


The memory on your system is a limited resource. The 
amount of memory needed by a job cannot exceed the 
available memory on your system, or RMON will not be able 
to run the job. As your programs become complex, the need 
to make efficient use of memory increases. 

An issue related to memory use is speed of program 
execution. Certain methods of increasing execution speed 
do so at the cost of increased program size; on the other 
hand, other methods decrease program size at the cost of 
slower execution speed. For example, overlaying a pro- 
gram can decrease its size but also slows execution. Once 
you learn how to modify and control memory use on the 
RT-—11 system, you can select the proper balance of size 
versus execution speed for your particular application. 

This chapter discusses two ways you can modify the 
way that RT—11 uses memory. The first, called dynamic 
allocation of memory, is to issue requests that allocate 
memory to your job while it is running. The second is to 
contro] the swapping of the USR during the execution of 
your program. You will see how each method affects both 
the size and execution speed of your program. 

The programmed requests discussed in this chapter are: 
SETTOP, IGETSP, .LIMIT, .LOCK, .UNLOCK, and .TLOCK. 
When you have completed this chapter, you will be able to 
write code to request dynamic allocation of memory to a 
program; control the swapping location of the USR; and 
increase the speed of consecutive USR operations and 
minimize blocking of either job. 
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Standard Memory Use 


Figure 63 shows a typical allocation of memory under the 
Foreground/Background monitor. Memory use under the SJ 
monitor is similar, but there is no foreground job; there- 
fore, all loaded device handlers are in a contiguous area 
between RMON and the USR. 

The background job area can be divided into the job 
itself—the code that you write—and the stack. The job starts 
at the base address at which it was linked, default 1000 
(octal). By default, the stack starts at the base address and 
extends downward to location 500 (octal). (The stack po- 
sition can be changed by the /STACK option of the LINK 
command.) 

The foreground job area is made up of the foreground 


Figure 63. 
Allocation of Memory with Active Foreground and 
Background Jobs 
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job, its stack, and its impure area. As with a background 
job, the foreground stack is placed immediately below the 
job’s base address by default. Its size is fixed when the job 
is linked. Default size is 128 (decimal), 200 (octal), bytes. 
The impure area is always placed at the bottom of the fore- 
ground area. (Remember that the background impure area 
is within RMON.) If you use the /BUFFER option of the 
FRUN command, space is reserved in the foreground area 
above the foreground job. | 

The absolute location of the foreground area in mem- 
ory is determined by the amount of memory on your sys- 
tem, the size of the system device handler, RMON, and the 
other components (device handlers and system jobs) that 
are loaded into the area below RMON before the FRUN 
command is issued. Figure 64 shows the detail of the fore- 
ground and background areas. 

Each job has a high and a low limit. These limits are 
used by RMON to make sure that certain operations re- 
quested by a job do not affect any locations outside that job’s 
area. For example, a program cannot perform I/O to a buffer 
outside its limits. A program can find out what its limits 
are by issuing a GTJB request. 

The low limit of a job is the base of the area shown in 
figure 64. It does not change during execution. When a job 
is started, its high limit is the last location used in the load 
image (the last word used for instructions or for data stor- 
age requested within your program). For a background job, 
you can extend the high limit using the /TOP option of the 
LINK command; for a foreground job use /BUFFER of the 
FRUN command. The high limit can also be changed dur- 
ing execution. By raising its high limit, a job can request 
dynamic allocation of memory. This action also affects USR 
Swapping. - 


Dynamic Allocation of Memory 


Memory to be used for data storage can be allocated to your 
program in two ways. First, you:can reserve storage within 
the load image itself; the corresponding locations are re- 
served in memory when the job is loaded into memory. You 
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Figure 64. 
Detail of Foreground and Background Areas 
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usually reserve such storage locations using storage direc- 
tives in MACRO-11 and variables in FORTRAN IV. (Some 
linker options also affect positioning of program compo- 
nents within the load image, and therefore, indirectly af- 
fect the way storage is reserved there.) Second, you may re- 
quest that dynamic allocation of memory take place during 
your program’s execution. 

The performance of some programs is directly related 
to the amount of memory available for the programs. The 
/ more memory available, the better they will run. The im- 
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provement may extend the range of external conditions that 
they can handle or result in higher execution speed. For 
example, most programs that do I/O to a mass storage de- 
vice will sun faster given a larger I/O buffer, because it is 
almost always faster to read or write multiple blocks in one 
request than to do consecutive reads or writes of one block 
each. As another example, consider a program that accepts 
data from an input device in high-speed bursts. The more 
buffer space available to the program, the more data the 
program can accept before running out of room. This al- 
lows higher data rates. 

The benefit of dynamic allocation of memory over re- 
serving storage is that the amount of storage requested can 
be controlled by: 


¢ The actual needs of the program, as determined dur- 
ing execution 


e The actual amount of memory available at execution 
time 


If you want to reserve space for these buffers as you 
write the program, you will have to determine how much 
buffer space you need. If a small buffer is reserved, the pro- 
gram may not perform as well as it could. If a larger buffer 
is reserved, the program may not fit into the amount of 
memory available at execution time. The problem is that, 
at the time you write a program, you do not know how much 
memory will be available when you execute it. The best so- 
lution, therefore, is not to leave space for such a buffer when 
you write your program, but rather, request dynamic allo- 
cation. 

A MACRO-11 program can request dynamic alloca- 
tion of memory by issuing a .SETTOP request. The effect 
of this request is to change the high limit of the program 
and gain the use of additional space. 

The FORTRAN IV OTS (which is written in MACRO— 
11) automatically issues a .SETTOP request when you start 
up a FORTRAN IV program. The memory returned by this 
request is used as a workspace by the OTS for purposes such 
as temporary storage, I/O buffers, and space for device 
handlers. 
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The .SETTOP requested by the OTS gets as much 
memory as is available from RT-—11, and all of the work- 
space is reserved for OTS use. Therefore, there is no re- 
quest that you can use within your FORTRAN IV program 
to get more memory from RT—11. However, by using the 
IGETSP (get space) request, you can ask the OTS to allo- 
cate part of its workspace for your use. IGETSP is a request 
by which a FORTRAN IV program can request dynamic al- 
location of memory. 


The .SETTOP Request 


To determine the new high limit to request, use the .LIMIT 
directive. The following example shows a request for a buffer 
of 1000 (octal) bytes. 


Get ‘current hiae 
Add 1000. ane 


To allocate to your program as much memory as pos- 
sible, request a high limit that you know cannot possibly 
be given to you. 
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RMON will change your request to the highest it can give 
you. Take the new high limit returned in RO. 

The following example shows how to get as much 
memory as possible without forcing the USR to swap out 
because of .SETTOP. USR swapping is discussed in detail 
later in this chapter. 
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-SETTOP under the Extended Memory Monitor 


Using a feature known as a virtual .SSETTOP, a MACRO-11 
program executing under the XM monitor can request dy- 
namic allocation of extended memory (that is, memory above 
28 Kwords). This differs from a .SETTOP under the SJ or 
FB monitors and from a nonvirtual .SETTOP under the XM 
monitor, because each of those requests returns only mem- 
ory under 28 Kwords regardless of how much memory is 
on the system. Two characteristics of the virtual .SETTOP 
make it very useful: 


¢ Onan XM system, you can obtain more memory by 
using a virtual .SETTOP to get memory above 28 
Kwords than you can by using a nonvirtual .SETTOP. 


e The virtual .SETTOP is an easier way to use ex- 
tended memory than the extended memory pro- 
grammed requests. 
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To request allocation of extended memory using a vir- 
tual .SETTOP, the job must be a virtual job. It is not nec- 
essary for you to understand the details of virtual and priv- 
ileged mapping in order to use the virtual SETTOP feature. 
To make your job virtual, you must set bit 10 of word 44 
in the job’s load image, the job status word. You can either 
patch the word or set it, using an absolute program section 
in your source code. 


—-WORD 2000 ;C€BIT 10) 
meRObC lig A neem 


a cameaneeemaete ceases 
: 

£ ated 
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Then issue a .SETTOP. You can ask for a new high limit 
of any address between your job’s next free address and 
177776. The next free address is the next 4-Kword bound- 
ary above the addresses used by your program, including 
the root and any /O or /V overlays (if the program is over- 
laid). The next free address is always printed on your load 
map. if you use the LINK/XM option or /V overlays. Your 
program can get its next free address at execution time if 
you use a .LIMIT assembler directive. This directive gen- 
erates two words of storage, the second being the next free 
address if you use LINK/XM or /V overlays. 

A virtual .SETTOP returns with two allocations: 


e A new range of addresses within your program. 


¢« A section of physical memory, taken from the mem- 
ory above 28 Kwords that RMON controls. You can 
refer to this section of physical memory by using this 
new range of addresses as you would any other ad- 
dresses within your program. 


On return from .SETTOP, RO contains the highest ad- 
dress that your job can now use. If RMON can give you all 
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that you asked for, the new address range available to you 
is from the next free address to the new limit you re- 
quested in the .SETTOP. 

If not enough memory is available above 28 Kwords, 
RMON decreases the size of your request, and the new high 
limit is less than you requested. If, on return from the 
.SETTOP, RO contains the next free address, no new mem- 
ory has been given to you. 


Restrictions on the Use of .SETTOP 


Certain restrictions apply when you use the .SETTOP pro- 
grammed request for virtual jobs under the XM monitor. 


1. You may not use addresses that lie between: 


a. Those available to you before the SETTOP (the highest 
address used by the root and any /O or /V overlay 
segments) 


b. The next free address (which is the first 4 Kword 
boundary above a.) 


An attempt to use those addresses may result in an 
execution error that will abort your program. 


2. The address you request in the .SSETTOP should be 
above the next free address or else no new memory 
will be given to you. 


3. The memory you get from .SETTOP cannot be used 
for queue elements or I/O channels. 


4. A virtual job cannot access anything outside its own 
area. This includes RMON (other than by using 
-GVAL), the I/O page, and the interrupt vectors. 


The IGETSP Routine 


The IGETSP routine requests that the OTS allocate a part 
of its workspace for your program use. When the main-line 
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routine of a job is written in FORTRAN IV, or when the 
OTS is initialized by a direct call to the OTS initialization 
routine, any request for dynamic allocation of memory 
should be made by a call to IGETSP. A FORTRAN IV call 
to IGETSP has the form: 


In this request: 


following: 


ISIZE = IGETSP (min,max,iaddr) 


min 


max 


iaddr 


ISIZE 


is the minimum acceptable size, should an 
area of the correct size not be available. 


is the size (in words) of the area that you 
would like allocated to you. 


is an INTEGER variable in which IGETSP re- 
turns the address of the area allocated to you. 


is an INTEGER variable that receives the ac- 
tual size of the area allocated to you (min 

<= ISIZE <= max). If IGETSP cannot allo- 
cate an area of min words or larger, ISIZE re- | 
ceives a negative value. 


You cannot use iaddr to refer directly to the buffer be- 
cause iadder is not the actual buffer but an INTEGER vari- 
able that contains the buffer address. You can do one of the 


Use the SYSLIB routines IPEEK, IPEEKB, IPOKE, 
IPOKEB in order to reference this buffer from the 
routine that issued the IGETSP. 


Use an assembly language subroutine to reference it. 


Use a routine like INDIR (chapter 17, ‘“Transferring 
Data Between Jobs’’) to allow the routine that issued 
the IGETSP to pass the buffer indirectly to a FOR- 
TRAN IV subroutine. The following example shows 
how you might request a buffer using IGETSP and 
then do I/O to that buffer using INDIR to pass the 
buffer to IREADW indirectly. 
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EXAMPLE 


ISIZE=IGETSP (256,512, 1ADDR) 
IF CISIZE.LT.0) STOP ’NOT ENOUGH BUFFER SPACE’ 
IERR=INDIRCIREADW,0,ISIZE,1,TADDR,0,1BLK,0,I1CHAN)D 
C CDIRECT REFERENCES ON ALL ARGUMENTS EXCEPT IADDR. 
C SEE THE LISTING OF INDIR IN CHAPTER 17) 
IF CIERR.LT.0)9 STOP ‘“READW ERROR’ 


na ANN betas 
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You may call IGETSP and be given additional mem- 
ory, but at a later time your program may fail because there 
is not enough workspace for the FORTRAN OTS. This is 
because the OTS cannot tell how much workspace it will 
need in the future. Therefore, it allocates memory based on 
its workspace needs at the time of the request. 

If your program has this problem, you should lower the 
“max” argument in the IGETSP call until the program runs 
successfully. This is not a dependable solution as you have 
no assurance that the problem will not occur again if a dif- 
ferent execution path through your program results in more 
use of the OTS workspace. 


USR Control 


The USR is designed to swap in and out, as needed, during 
program execution. Controlling where and when the USR 
swaps is another method to make efficient use of memory 
and achieve fast execution speed. 


The Swapping Algorithm 


The following conditions affect USR swapping. 


e Under the XM monitor, the USR never swaps. 
e If the USR is set to NOSWAP, it does not swap. 
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¢ If the USR is set to SWAP and the background high 
limit is above the base of the USR, the USR swaps. If 
the background high limit is below the base address 
of the USR, the USR does not swap. 


e The background high limit is affected by a .SGSETTOP 
request. You can use .SETTOP to set the high limit 
above or below the USR base address to control | 
whether or not the USR will swap. - 


The USR swaps out when a background program is run 
whose high limit is above the base address of the USR, or 
when a background program performs a .SETTOP above the 
base address of the USR. The USR swaps in during pro- 
gram execution when a job issues a request that needs code 
in the USR. Some of these requests are: 


e Device handler operations: FETCH, DSTATUS 
e I/O preparation: QSET, CDFN 


e Directory operations: ENTER, LOOKUP, CLOSE, 
RENAME 


e CSI operations (including GTLIN, which is imple- 
mented within the CSJ) 


Complete lists of the requests that use the USR are dis- 
cussed in chapter 1 of the RT—11 Programmer’s Reference 
Manual. 

The address at which the USR is swapped is deter- 
mined by the following conditions: 


e If the contents of word 46 are 0, the USR swaps in (at 
its default location below RMON) any foreground or 
system jobs and any loaded handlers. 


¢ If word 46 is not 0, the USR swaps at the address 
specified by the contents of word 46. 


¢ The foreground job should always set an address into 
word 46. If the foreground job issues a USR request 
when word 46 is 0, and the USR is not resident, a fa- 
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tal error may result and the foreground job will be 
corrupted. 


¢« By default, the FORTRAN IV OTS sets the USR to 
swap at the base of the program. Except in small 
FORTRAN IV programs, this is usually a good place 
for it to swap. If you have a small FORTRAN IV pro- 
gram, either set the USR to NOSWAP, or compile 
background jobs with the /NOSWAP option. The /NO- 
SWAP option causes the OTS to do a .SETTOP to the 
base of the USR instead of up to the limit of the sys- 
tem. 


When actual swapping occurs, the part of the job that 
is within the swap area of the USR is written out to 
SWAP.SYS. Then the USR is read into the swap area and 
executed. When the USR is done, the portion of the pro- 
gram that was written to SWAP.SYS is read back into the 
swap area. 


Problems and Restrictions 


If you allow the USR to swap, certain problems can result. 
Random errors can occur if, when swapping, the USR over- 
writes certain types of code or data that it may need while 
executing. See chapter 2 in the RT—11 Software Support 
Manual for a detailed list of the errors. In general, do not 
let the USR swap overwrite: 


e The stack 


e Any data that the USR itself needs—file definition 
blocks, for example 


e Any code that may be entered asynchronously: inter- 
rupt service routines, device handlers, or completion 
routines 


USR swapping takes time because of the disk accesses 
needed to write to and read from SWAP.SYS and to read 
the USR itself. 
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To solve problems caused by the USR overwriting cer- 
tain code or data, you can either relink your modules so 
the USR swaps information that does not cause problems, 
or you can move the USR by setting an alternative swap- 
ping location into word 46. 

Two areas which give you an opportunity to minimize 
delays caused by USR swapping are sequential USR oper- 
ations and USR contention. 


Sequential USR Operations 


If one job executes several USR operations sequentially while 
the USR is swapping, each request needs three disk ac- 
cesses for the swapping operation: write to swap file, read 
USR, and read swap file. Unnecessary disk accesses are made 
if the USR completes its operation and swaps out, then 
swaps right back in again. 

To prevent excessive swapping, you can issue a LOCK 
request before the first USR operation and an UNLOCK re- 
quest after the last to hold the USR in memory while se- 
quential USR operations are performed. The USR swaps in 
if it is not resident when the LOCK is issued, and it stays 
in memory until the UNLOCK is issued. At that time nor- 
mal swapping continues. 

Be sure that neither the LOCK request, the UNLOCK 
request, nor any code or data needed between issuing the 
LOCK and issuing the UNLOCK, resides in the area where 
the USR swaps. 

If your job meets the following three conditions, you 
can keep the USR resident at selected times: 


¢ It is a background job. 
-¢ It has a high limit below the base address of the USR. 
e It normally performs a .SSETTOP to get as much 


buffer space as it can. 


Issue .SETTOP requests below the base of the USR to 
allow the USR to stay resident, and above the base of the 
USR to force it to swap out. 


USR Contention 
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Common practice is to issue requests such as .FETCH, 
ENTER, .LOOKUP, and .QSET before issuing a .SETTOP 
(or, if you need some buffer space you can first issue a 
.SETTOP to the base of the USR). When these are com- 
pleted, issue a .SETTUP above the base of the USR. When 
file use is completed and you want to close your channels, 
issue a .SETTOP to the base of the USR or to your original 


program high limit. This lowers the high limit and allows 


the USR to become resident once again. 


The USR is not reentrant; it can be used by only one pro- 
cess at a time. Under the FB monitor, it is possible that while 
one job is using the USR, another job also needs to use the 
USR. This condition is known as USR contention. To pre- 
vent USR contention from causing execution errors, the 
monitor assigns ownership of the USR. As soon as the USR 
starts to execute a request for a job, or when a job issues a 
LOCK, that job is assigned USR ownership. Ownership is 
released when the USR completes the request or, if a LOCK 
has been issued, ownership is released when that job is- 
sues an UNLOCK. If, while one job owns the USR, a sec- 
ond job issues a request that needs the USR, RMON blocks 
the second job until the first job releases ownership. This 
blocking of the second job is called USR lockout. 

With the exception of certain uses of communication 
requests discussed in chapter 17, “Transferring Data Be- 
tween Jobs,’’ USR lockout is the only state under the FB 
monitor in which a background job can force the fore- 
ground job to become blocked. 

While USR lockout prevents execution errors caused 
by reentrance of the USR, it has the side effect of blocking 
the second job. If the first job has issued a LOCK request, 
the second job can be blocked out for a long time. This can 
be unacceptable if the second job is a real-time application 
that needs constant monitoring and control of external de- 
vices. 

To prevent USR lockout from blocking a job, the job 
can issue a TLOCK request which: 
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e Tests if another job owns the USR 
e Performs a LOCK if no other job owns the USR 


e Returns an error if another job does own the USR 


If a job that needs the USR issues a TLOCK request and 
receives an error in return, that job can either continue 
processing and try the TLOCK again or print an error mes- 
sage, close down the operation it is monitoring, and exit. 


In this exercise you will modify one of the file-copying pro- 
grams you created in practice 14—1 (either PR1801.MAC or 

PR1802.FOR). Create a new version of the program accord- 

ing to the instructions below: 


1. Use a buffer that is allocated dynamically. Make the 
buffer as large as you can, given the available memory. 
If you are programming in FORTRAN IV, you can use 
the INDIR routine. 


Keep the USR resident by doing a .SETTOP only to the 
base of the USR. 


Maintain ownership of the USR during the operations 
that need the USR and during the close or purge 
operations. . 


The FORTRAN program will run only if you set the USR to 
NOSWATP or use the /NOSWAP option when you compile 
the module. If the USR is set to SWAP, the program will 
fail at the call to lock the USR in memory during the 
SETUP routine. 


References 


RT-—11 Programmer’s Reference Manual. Chapters 2 and 3 dis- 
cuss the LOCK and UNLOCK request in MACRO-11 and FOR- 
TRAN IV programs. Chapters 1 and 2 contain material on the 
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.SETTOP request in an extended memory environment and ex- 
plain how the .SETTOP issued by the OTS works. Chapters 1 and 
3 provide detailed information about IGETSP. 


The RT—11 Software Support Manual. Chapter 2 discusses the 
USR. Chapter 4 describes virtual jobs with SETTOP in extended 
memory. 
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Using the 
Command String 
Interpreter 


Some operations related to file I/O are needed by many 
programs. These operations include parsing command 
strings, fetching device handlers, opening channels, and 
connecting files to channels. The Command String Inter- 
preter (CSI) performs these operations and is accessible from 
both MACRO-11 and FORTRAN IV programs. 

This chapter focuses on the capabilities and use of the 
CSI. Using a programmed request to accept and parse a 
command string, fetch handlers, and open channels, you 
will write a MACRO-11 program that accesses the files you 
specify. You will also learn to write a program that ac- 
cesses files using a programmed request to accept and parse 
the command string without fetching handlers or opening 
channels. Given a list of legal options and correct re- 
sponses, you will write code that responds to options in- 
cluded in a command string. 


ae7 
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Command String Interpreter 


The Command String Interpreter (CSI) was implemented to 
provide programmers with an efficient, standard method of 
starting file I/O activities. The CSI processes a command 
string for the program that calls it. The command string can 
come from either the terminal, an indirect command file, 
or a buffer in the program. The information in the com- 
mand string may include: 


e Names of files to be used for input 
e Names of files to be used for output 


e Command options defined by the programmer 


The two programmed requests that call the CSI (CSIGEN 
and CSISPC) are discussed later. The operations that the CSI 
performs for the program depend on the information in the 
command string and which CSI programmed request is used. 
The CSI can be called on to: | 


¢ Get a command string from the operator 
¢ Parse a command string 


¢ Convert file specifications from ASCII to RAD50 
format 


¢ Fetch device handlers 
¢ Open channels to input and output files 


¢ Return a summary of options to the calling program 


Format of a Command String 
_The CSI processes a command string in the form: 
OUT1,0OUT2,OUT3=IN1,IN2,IN3,IN4,IN5,IN6 
In this command: . 


¢ From 0 to 3 output files are allowed, with the file 
name format: : 
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DEV:FILNAM.TYP[n] 


Device defaults to DK: and the name, type, and num- 
ber can be omitted if the device is not file structured. 
The program calling the CSI can specify a default file 
type. Here “‘[n]”’ is the requested length of the output 
file in blocks. Values are the same as those for the 
ENTER request’s length argument. The default length 
is 0. 

¢ From 0 to 6 input files are allowed, with the format: 
DEV:FILNAM.TYP 


The comments made above for output files apply to 
input files also. 


¢ The equal sign (=) separates the list of output files 
from the list of input files. This symbol must be pres- 
ent if any output files are specified but can be omit- 
ted if only input files are specified. 


If fewer than three output or six input files are specified, 
the following conventions apply: 


e If the file at the beginning of the list is omitted, 
indicate the fact by including the comma that would 
follow it, had it been present. 


¢ If the omitted file is at the end of the list, the comma 
following it, if any, may be omitted. 


Table 18 shows these conventions. 


Table 18. 

Examples of Command Lines 

Files Command 
Three input files only A,B,C 
The first output and first input files A=B 
The second output and no input files ,LP:= 


Third output file and second input file »,Q=,Z 
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Options or Switches 


You can follow any file specification in the command line 
with an option (also referred to as a switch). The simplest 
form of an option is: 


IX 


where “‘X” is any letter. An option may be followed by 
either: 


¢ A number: octal (default) or decimal (use a decimal 
point). For example, /X:5 and /X:12. 


¢ A word of up to three characters. For example, 
/X:aaa. 


Each option value must be preceded by a colon. The fol- 
lowing example shows two command strings including 
options. 


ee os : EXAMPLE aoe 
fee “OUTFIL/K: cee _=INFIL- oo 
z oo OUTFIL, LSTFIL/L: BEX: ME= ANF IL eae 


riscrceaisarenes new ohio iisiN Nw le NeRaac ddan ahtdeisic bites aw ete cena ccan oie i SNE OINE NEN ROBINS dha oN aE Gon TB Gari es onion Sia ee a ASE ha ona 


The program calling the CSI defines: 


¢ Which options are legal, and the meaning of each 


¢ Whether an option takes a value, which values are le- 
gal, and their meaning 


¢ Whether an option applies only to the file that di- 
rectly follows it, to multiple files, or to the full com- 
mand line 
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Program Interface with the CSI 


You call the CSI using programmed requests. The CSTRING 
argument of the programmed request for the CSI specifies 
the source of the command string. If you want the CSI to 
take a command string from a buffer within the program, 
the buffer address is used as the CSTRING argument. Usu- 
ally, however, you want to take the command string from 
the operator. If you leave out the CSTRING argument, the 
CSI uses the GTLIN request to get a command line. To have 
the CSI get the command string from a buffer within your 
program rather than from the terminal or a command file, 
follow these procedures: 


¢« Store the command string in the buffer in ASCIZ 
format. 


¢ MACRO-11: Supply the address of the buffer as the 
CSTRING argument. 


¢ FORTRAN IV: The CSTRING argument must be the 
name of the array containing the command line 
string. 


The DEFTYP argument to the CSI programmed re- 
quest allows you to specify default file types to be used if 
the operator omits the file type in the command line. You 
specify these default file types in a four-word RAD50 ar- 
gument block. The contents of this block are shown below. 


Word 1 _ __—scDefault File Type 
For All Input Files 


Word 2 __—sCODeefault File Type 
For First Output File 


“Word 3 ___—Default File Type 
, For Second Output File 


Word 4 __—sCDefault File Type 
.For Third Output File 
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Use the following procedures to set up and gain ac- 


cess to the four-word argument block: 


¢ If you do not want to recognize default file types for 


one or more files specified in the default block, make 
the corresponding words in the block 0 (RAD50 for 
three spaces). 


MACRO-11: Create the DEFTYP argument by speci- 
fying the address of the DEFTYP block. 


FORTRAN IV: Create the DEFTYP argument by speci- 
fying the name of the array or variable used as the 
DEFTYP block. 


The address of this block (MACRO -11) or the name of 


the array being used as the block (FORTRAN IV) is pro- 
vided as the argument to the CSI requests. 


Each file that a user specifies in a command string is 


assigned a file number in the range 0 to 8 (decimal) or 0 to 
10 (octal). These file numbers are assigned as follows: 


Files in a full command string of three output and 
six input files are assigned the numbers 0 to 8, work- 
ing from left to right in the command string. 


If any of the nine files are omitted, the numbers that 
would have been assigned are not used. Figure 65 
shows this by giving the file number assignments for 
a number of sample command strings. The matrix on 
the right indicates the numbers assigned by the CSI 
to the files in the command line on the left. 


As we have said, options may be accompanied by val- 


ues. The CSI passes values to your program as follows: 


Numeric values are passed as a one-word binary 
number (INTEGER data type in FORTRAN IV). 


Values containing alphabetic characters are passed as | 
a single word of RAD50 code. 
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e« An option that has multiple values is taken as multi- 
ple occurrences of the same option. For example, if 
the user types: 


FILENAM/X:5:0 
the option and its values are interpreted as: 


FILENAME/X:5/X:0 


Figure 65. 
Assignment of File Numbers by the CSI 


COMMAND FILE NUMBERS ASSIGNED 


A,B,C = L,M,N,O,P,Q 


Z=Y 


The CSI has two different modes of operation: general mode 
for MACRO-—11 only, and special mode for MACRO-11 or 
FORTRAN IV. Table 19 shows the differences between 
general and special mode CSI functions. 


Calling the CSI in General Mode (.CSIGEN) 


CSI (general mode) is accessed using the .CSIGEN pro- 
grammed request in the following form: 
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.CSIGEN | handler-address, deftyp, cstring, linbuf 
In this request: 


handler-address is the base address of a buffer into 
which the CSI is to fetch any 
needed handlers. 


deftyp is the address of the four-word 
RAD50 block that is used to con- 
tain the default file types. 


cstring is the address of the command 
string buffer, or 0 if the command 
must come from GTLIN. 


linbuf is optional. If present in the re- 
quest, it is the address of a buffer 
into which the CSI copies the com- 
mand string in ASCIZ form. (An 
example is a program to produce a 
listing file that includes the com- 
mand line for documentation pur- 
poses.} The MACRO—11 assembler 
carries out this request. 


Table 19. 
General and Special Mode CSI Functions 


General Mode Special Mode Both Modes 


Return RAD50 Get command string from: 


file specifications ; 
LOOKUP input files | to program Memory 


ENTER output files 


Fetch handlers 


¢ Terminal 
¢ Command file 


Parse command string: 


¢ Identify files by file number 
e Identify options and values 
e Link option with file number 


Return option information to 
calling program 


Convert file specifications to 
RADS5O format 
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Device handlers are fetched to the location that you 
specify. This is usually the high limit of your program. If 
multiple handlers are needed, the next handler is fetched 
into memory at locations above the previous one. On re- 
turn from the .CSIGEN request, RO points to the word above 
the last handler fetched. If none are fetched, RO contains 
the handler-address argument. 

Each file specification in the command string is opened 
on the channel given by its file number. Input files are 
opened using LOOKUP; output files using ENTER. 


2 REE aN AN SOOT ELMER NM ANTES AE AE SON AE A NN SINT ATI OO BON NEN SNE OEE ATTA EARN OCONEE AN 
wey we? 2 : c sine ‘i . é i 


+ 
ay 


EXAMPLE : 
Foo. OBJ=FO0. mac. Pes ce pe 


In this command string, FOO. OBJ is opened on chan-. oan 
nel 0 using ENTER and FOO.MAC i is opened, ON ese 
channel 3 using LOOKUE: ar ; 

| 


Incnicinsnietninatatiinanenddritin insatiable didnt bt ird nosininetntis ciitti iht 


es 
eS 3 
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When executing a .CSIGEN request, the CSI always 
closes channels 0 to 8 before performing any ENTER or 
LOOKUP operations. Therefore, any files that you have 
opened on these channels before issuing the .CSIGEN re- 
quest are closed. Any channels not used in the command 
string are left inactive on return from the .CSIGEN request. 

Options are returned on the stack. They are popped off 
the stack in the order listed below. 


1. One word containing the number of options specified 
in the command string. Remember that multiple op- 
tion values are returned as repetitions of the option. 


2. A one- or two-word descriptor for each option (one 
word if no value; two words if a value was given). 


The return of option information on the stack is shown 
in figure 66. Figure 67 shows the format of an option word. 
Before calling the CSI, save the current stack pointer 
(SP) if you plan to ignore options or if your program is de- 
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Figure 66. 
Return of Option Information on the Stack 


N (NUMBER OF OPTIONS 
GIVEN) 


OPTION DESCRIPTOR 
MAY BE: 


OPTION DESCRIPTOR 


OPTION DESCRIPTOR 


BOTTOM OF STACK ——> 


INCREASING 
ADDRESSES ON 
STACK 


NUMBER OF 
OPTION 
DESCRIPTORS 
=WN . 


STACK POINTER ———» 
BEFORE CSI 
CALL 


Figure 67. 
Format of an Option Word 


BIT NO. 15 14 8 7 


il FILE NUMBER 


ASCII CODE FOR 


OPTION CHARACTER 


AN OPTION DESCRIPTOR 


OPTION WORD 


OR 


OPTION WORD 


VALUE WORD 


= 11F OPTION HAD A VALUE (VALUE WORD FOLLOWS ON STACK) 


= 21F OPTION HAD NO VALUE (NEXT WORD ON STACK IS 


ANOTHER OPTION WORD) 


signed to abort an illegal option. You can use the saved SP 
value to restore the stack to the state it was in before the 


CSI call. 


Always restore the stack to the state preceding the call, 
even if no options are expected, because one word (with 
the value 0) is pushed on the stack even if no options are 
included. The general flow of control for option processing 


is as follows: 
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1. Use the contents of the first word on the stack as a 
counter for popping off option descriptors. 


2. As you pop off each option word, pop off the value 
word if the option word is negative. 


3. Set flags or values for use in the program. 


4. Reset the stack. 


As an example of CSI general mode, see the segment 
of code in figure 68. This code is set up to function as part 
of a program that will accept /C as an option. 


Figure 68. 


Code Showing Option Processing under General Mode 


CLR 
MOV 
-CSIGEN 


TST 
BEG 
CMP 
BNE 
CMPB 
BNE 
INC 


CLEAN: MOV 


DEFEXT: .WORD 
SAVSP: .WORD 
HSPACE: .BLKW 


R4 ;USE R4 AS FLAG WORD 
SP ,SAVSP ;SAVE STACK POINTER 
~“HSPACE ,__#DEFEXT,~-#0 
;GET CSI STRING FROM KEYBOARD 


(SP) ;OPTIONS SET? 

CLEAN 3NO, CONTINUE 
CSP)+,_#1 ;ONE OPTION? 

CLEAN 3NO, CONTINUE 
CSP)+,_#°C ;YES, WAS IT C? 

CLEAN 3NO, IGNORE 

R4 ;YES, SET FLAG FOR LATER USE 
SAVSP,SP ;RESTORE STACK POINTER 
0,0,0,0 

0 

1024. ;HANDLER SPACE 


Calling the CSI in Special Mode 


(.CSISPC or ICSI) 


Whether you are programming with MACRO-11 or 
FORTRAN IV, you can use CSI special mode. You may want 
to use it to check a command string in a MACRO-11 pro- 
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gram before proceeding with operations such as fetch, 
lookup, or enter. You may also use it to check for: 


¢ Reserved file names 
¢ The number of files in the command 
¢ The output file size 


e Old versions of output file specifications (before 
doing an enter) 


¢ Default file types to be determined by options (for ex- 
ample, LIBR can produce either .OBJ or .MAC files) 


The MACRO-11 request for calling CSI in special 
mode is: 


.CSISPC files, deftyp, string, linbuf 


Here ‘“‘files’’ is the address of a 39-word block to be used 
for file specifications and ‘‘linbuf’’ is the storage address for 
the original command string in ASCII. All other arguments 
for this request are identical to those needed by the .CSIGEN 
request. 

The FORTRAN IV request for CSI access is: 


IERR=ICSI (files,deftyp,cstring,options, N) 
In this request: 


files is an array of 39 words to be used to hold 
file specifications. 


‘deftyp is a four-word area containing RAD50 for- 
mat default file types. 


cstring if present, is an array containing a com- 
mand string in ASCIZ format. If this argu- 
ment is omitted, CSI expects to receive the 
command string using GTLIN. 


options can be omitted if N is 0; if N is not 0, this 
argument must be the name of an array of 
size 4*N. This array is used by ICSI to re- 
turn option information. 
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If this array has the dimensions: 


INTEGER OPTIONS (4,N) 


then all the elements of the array have the 
meaning indicated in table 20 for all values 


of J from 1 to N. 


is the maximum number of options 


allowed. 


In setting up calls to ICSI, fill in the first row of the op- 
tions array before calling ICSI. Follow these procedures: 


¢ Place any legal option in at least one column of the 
options array. 


e Ifa specific option can be used legally more than 
once in a command, it must head as many columns 


Table 20. 
Information Contained in Option Array 
Name of Description Default Filled in 
Element Contents Value By Notes 
OPTIONS(1,J) ASCII code for None User job Must be filled 
option character in before 
calling ICSI 
OPTIONS(2,J) “Option present” 0 ICSI 1 means option 
appeared without 
a value 
2 means option 
appeared with a 
value 
(if O, then 
option did not 
appear in 
commands) 
OPTIONS(3,J) File number 0 ICSI Only important if 
OPTIONS(2,J).NE.O 
OPTIONS(4,J) Value .0 ICSI ° = Only important if 


OPTIONS(2,J) =2 
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Figure 69. 


ICSI Filling in the Options Array 


FIND NEXT COLUMN 
WITH MATCHING 
CHARACTER 


GET NEXT OPTION YES 
FROM COMMAND 


CLEAR ROWS 2-4 OF 
ARRAY TO 0’'S 


ANY 
OPTIONS 
PASSED 


NO 


RETURN SUCCESS- 
FULLY TO USER 
YES 


GET FIRST OPTION 


FIND A COLUMN IN 
ARRAY WITH MATCH- 
ING CHARACTER 


NO RETURN ERROR 
TO USER 


ALREADY BEEN 
USED? (CHECK 
OPTION (2,J) 
1S IT # 0?) 


NO 


WAS 
A VALUE 
GIVEN WITH 
THIS OPTION 


SET OPTION (2,J) =2 
SET OPTION (4,J) = 


VALUE 


NO 


SET OPTION (2,J)=1 


SET OPTION (2,J) = 
FILE # ON WHICH THIS 
OPTION WAS FOUND 


ANY 
MORE 
OPTIONS IN 
COMMAND 


NO RETURN SUCCESS- 
FULLY TO USER 


Practice 
19—1 
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as the maximum number of times it can appear in 
the command. 


¢ Remember that an option with multiple values (for 
example, /X:5:2) is taken as the same option repeated 
with different values (/X:5/X:2). 


The flowchart in figure 69 shows the procedure used 
by ICSI to fill in the options array. Read this flowchart in 
conjunction with table 20 because it shows how the array 
described in the table is filled in when the ICSI request is 
used. 
The programs (PR1901.MAC and PR1901.FOR) which 
follow show the use of the two CSI modes. Both programs 
execute a single-buffered copy routine based on the pro- 
grams introduced in chapter 15, ‘“Using Nonsynchronous 
Queued Input/Output.” In the MACRO-11 routine 
(PR1901.MAC), the command string is processed using the 
CSI in general mode. The FORTRAN IV _ program 
(PR1901.FOR) performs the same functions. The CSI spe- 
cial mode is used in this program. 

When called in special mode; the CSI returns infor- 
mation on options and file specifications to the user job. The 
information on file specifications is returned in RAD50 for- 
mat, in a 39-word block. You allocate the full 39-word block, 
even if you expect only one or two files. The CSI fills any 
unused areas with zeros. The contents of such a block are 
shown in figure 70. 


Write a program named PR1902 (in either MACRO-11 
or FORTRAN IV) that performs the following 
operations: 


a. Accepts a CSI command string from the terminal. 


b. Creates a file for output with the name specified in 
the command string (ignore input file specifica- 
tions). 
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Generates 10 blocks of data containing the positive 
integers 1 to 2560 stored in sequence. Each block 
of data is to be written out to the file after it is gen- 
erated, using synchronous write programmed 


requests. 


Closes the file. 


2. Run the program and specify an output file name. 
Check the output file contents using the DUMP utility. 


Figure 7 


0. 


File Specifications Returned by CSI Special Mode 
in a 39-word Block 


OUTPUT 
FILES 


FILE #0 
THREE 
BLOCKS 
SWORE FILE #1 
EACH 
FILE #2 
FILE #3 
FILE #4 
SIX FILE #5 
BLOCKS 
4 WORDS : 
FILE #7 


FILE #10 


FORM OF DESCRIPTOR 
BLOCK FOR OUTPUT FILE: 


DEVICE NAME 


FILE NAME 


FILE TYPE 
SIZE 


RAD50 


FORM OF DESCRIPTOR 
BLOCK FOR INPUT FILE: 


DEVICE NAME 


FILE NAME 


RAD50 


FILE TYPE 
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PR1901.MAC .TITLE PR1901 SAMPLE I/0 PROGRAM 


Sample file copy program using the CSI to 
allow user to specify input and output files. 


-MCALL .EXIT -CSIGEN .PRINT 

-MCALL .READW .WRITW .CLOSE .SRESET 
EMTARG: .BLKH 6 ;EMT argument block 
LIMITS: .LIMIT 3;Program limits 
SPSAVE: .BLKW . 1 ;Saved stack pointer 
DEFTYP: .WORD 0,0,0,0 s;Default file exts 
BUFFER: .BLKW 256. ;File I/O Buffer 
ERROR: .BYTE ;Error status byte 
PRMPT: .ASCIZ “Specify QUTFILE=INFILE™ 
CSIERR: .ASCIZ “Error on CSI call" 
RERRMS: .ASCIZ “Read error, copy aborted" 
WERRMS: .ASCIZ “Write error, copy aborted" 
PRTCT: .ASCIZ “Protected output file already exists" 

EVEN 

«-SBTTL SETUP -- Setup Files For Copy 


This routine prompts for and opens both 
an input and an output file. The CSI is 
used to collect and process a command. 


Returns with C-Bit SET on error. 


MOV SP ,SPSAVE ;Save stack pointer 
-PRINT #PRMPT 3;Prompt for files 

MOV LIMITS+2,R1 ;Load high limit 
-CSIGEN R1,#DEFTYP, #0 sCall CSI 

MOV SPSAVE , SP ;Reset stack pointer 
BCC 10$ sBranch on success 
«PRINT #CSIERR ;Output error message 
SEC sIndicate failure 
RETURN sReturn to caller 
-SBTTL CPYRTN -- Synchronous Copy 


This routine copies the input file opened on 
channel 3 to the output file opened on 
channel 0. 


Returns with C-BIT SET on error. 


Note: All registers except RO are preserved. 


? 

CPYRTN: MOV R1,-CSP) ;Save register 
CLR R1 sReset block number 
CLRB ERROR ;Clear error flag 
-READW #EMTARG, #3, BUFFER, #256. ,R1 
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RDERR: 
WERR: 


EREXIT: 
EXIT: 


10$: 


CLSCHN: 


PRGCHN: 
RESET: 


BCC 
TSTB 
BEG 

BR 
-WRITW 
BCS ~ 
INC 

BR 
-PRINT 
BR 
~PRINT 
DECB 
MOV 
TSTB 
BEG 
SEC 
RETURN 
~SBTTL 
- CLOSE 
.-CLOSE 
BCC 
-PRINT 


» SRESET 
RETURN 
-SBTTL 
CALL 
BCS 
CALL 
BCS 
CALL 
BR 
CALL 
EXIT 
- END 


20$ ;Branch if read OK 
e*S2 sEnd-Of-File CEOF)? 
EXIT sBranch if so 

RDERR ;Issue error message 
#EMTARG, #0, #BUFFER, #256. ,R1 

WERR sBranch on write error 


“ R4 ;Update block number 


10$ sAnd read next block 
#RERRMS s;Ilssue read error 
EREXIT 3; message and exit 
#WERRMS sIssue write error 
ERROR ;Set error flag 
CSP)+,R1 ;Restore register 
ERRGR. ;Set C-Bit? 


~10$ sBranch if not 


sSet C-Bit 
sReturn to caller 
CLSCHN -- Close Files 
#3 3;Close input file 
#0 ;Close output file 
RESET ;Branch on success 
*PRTICT ;Issue protected file 
;Purged files 
;Reset system 
;Return to caller 
MAIN PROGRAM 
SETUP ;Open files 
START ;Repeat on error 
CPYRTN sCopy file 
1$ ;Branch on error 
CLSCHN ;Close the files 
2$ 
PRGCHN ;Purge the channels 
sExit 
START 
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PR1901.FOR PROGRAM PR1901 


Sample file copy program using the CSI to 
allow user to specify input and output files. 


LOGICAL*1 SETUP,CPYRTN 
LOGICAL*1 ERROR 


ERROR = SETUPC) ! Open files 

IF CERROR) GO TO 10 ! Repeat on error 
ERROR = CPYRTNC) ! Copy file 

IF CERRGR) GO TO 20 ! Stop on error 
CALL CLSCHN ! Close files 

GO TO 30 

CALL PRGCHN ! Purge channels 
CALL EXIT 

END 

FUNCTION SETUP 


This routine sets up the files for I/Q. 
Function returns .TRUE. on error. 


LOGICAL*1 SETUP 

INTEGER*2 INCHN,OUTCHN 

COMMON /CHNNLS/ INCHN,OUTCHN 
LOGICAL*1 FRSTTM 

DATA FRSTTM/.TRUE./ 

INTEGER*2 DEFTYPC4),FILESC39),LENGTH 
DATA DEFTYP/4*0/ 

IF €.NOT. FRSTTM) GO TO 10 


Allocate channels only once. 
INCHN = IGETCC) 
OUTCHN = IGETCC) 
FRSTTM = .FALSE. 


Output prompt and get command line, 


CALL PRINTC’Specify OUTFILE=INFILE’) 
IF CICSICFILES,DEFTYP,,,0) .NE. 0) GO TO 


Fetch device handlers 


IF CIFETCHCFILESC1)) .NE. 09 GO TO 101 
IF CIFETCHCFILESC16)) .NE. 0) GO TO 102 


Open input and create output file. 
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PR1901.FOR LENGTH = LOOKUPCINCHN,FILESC16)) 
(continued) IF CLENGTH .LT. 02 GO TO 103 
; IF CIENTERCOUTCHN,FILESC1),LENGTH) .LT. 
GO TO 104 
SETUP = .FALSE. ' -Success 
RETURN 


ERROR ROUTINES 


CALL PRINTC’Error CSI call’) 

GO TO 200 

CALL PRINTC’Error FETCH of output handler’) 
GO TO 200 

CALL PRINTC’Error FETCH of input handler’) 
GO TO 200 

CALL PRINTC’Error LOOKUP of input file’) 

GO TO 200 

CALL PRINTC’Error creation of output file’) 
SETUP = .TRUE. ! Error 

RETURN 

END 

FUNCTION CPYRTN 


Single buffered, synchronous copy routine. 
Function returns .TRUE. on error. 

LOGICAL*1 CPYRTN 

INTEGER*2 INCHN,OUTCHN 

COMMON /CHNNLS/ INCHN,OUTCHN 

INTEGER*2 BUFFERC256), BLOCK 

BLOCK = 0 ! Reset block number 


Read/write loop. 


IERR = IREADWC256,BUFFER,BLOCK, INCHN) 

IF CIERR .GE. 0) GO TO 30 ! Successful read 

IF CIERR .EQ@. (-1)) GO TO 150 ! End of File 

GO TG 100 ! Issue error message 

IF CIWRITWC256,BUFFER,BLOCK,OUTCHN) .LT. 0) 
GO TO 101 


BLOCK = BLOCK+1 ! Update block number 
GO TO 20 ! Read next block 


ERROR ROUTINES 


CALL PRINTC’Read error, copy aborted’) 
GO TO 140 

CALL PRINTC’Write error, copy aborted’) 
CPYRTN = .TRUE. 

RETURN 
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PR1901.FOR 
(continued) Successful return. 


CPYRTN = .FALSE. 
RETURN 

END 

SUBROUTINE CLSCHN 


Close files. 


INTEGER*2 INCHN,OUTCHN 

COMMON /CHNNLS/ INCHN,OUTCHN 

CALL CLOSECCINCHN) 

IF CICLOSECOUTCHN) .EQ@. 4) CALL PRINT 
C’Protected output file already exists’) 

RETURN 

END 

SUBROUTINE PRGCHN 


Purge channels. 


INTEGER*2 INCHN,OUTCHN 
COMMON /CHNNLS/ INCHN,OUTCHN 
CALL PURGECINCHN) 

CALL PURGECOUTCHN) 

RETURN 

END 


Reference 


RT-—11 Programmer’s Reference Manual. Chapter 2 discusses the 
preparation of a CSI call by using data structures for ICSI 
(FORTRAN IV) or .CSISPC (MACRO-—11) request. .CSIGEN re- 
quests are also covered here. 
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Writing 
Time-dependent 
Programs 


In many programming applications, you need to sample 
data after regular or random periods of time or perform tasks 
that run regularly or at set times. RT—11 runs on systems 
without a clock, but time-dependent routines require a 
KW11-L or KW11—P system clock. This chapter describes 
how the system stores and maintains the system date and 
time. It then explains how to use programmed requests and 
subroutines to access and use this information. 

Some systems have timer service support, a feature that 
allows you to schedule programs to be run at a given time 
of day or after a given period of time has elapsed. This 
chapter explains how to write such programs. 

The MACRO-11 programmed requests and subrou- 
tines discussed in this chapter include: .CMKT, .DATE, 
.GTIM, .MRKT, .SDTTM, and .TWAIT. The FORTRAN IV 
subroutines discussed include: CVTTIM, DATE, GTIM, 
ICMKT, IDATE, ISCHED, ISDTTM, ISLEEP, ITIMER, ITWAIT, 
IUNTIL, JJCVT, JTIME, MRKT, SECNDS, TIMASC, and TIME. 

If your system has a system clock, you will be able to 
write programs that convert the current system date and 
time into numeric or ASCII format. You will also be able 
to write a program that sets the system date and time. If 
your system supports timer service, you will be able to write 
programs that run at a specified time of day, run after a 
specified period of time, or suspend program execution for 
a specified length of time. 
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System Time and Date 


You can use the time and date features of RT—11 only if 
your system has a system clock. The system clock may be: 


e A KW11-L line frequency clock which interrupts or 
ticks, once for each cycle of the ac line (that is, 60 
ticks per second for a 60-Hz line, and 50 ticks per 
second for a 50-Hz line) 


¢ A KW11-P programmable real-time clock which can. 
tick at line frequency (60 Hz in the United States and 
Canada; 50 Hz in Europe, Mexico, and Australia) or 
can be programmed to tick at a different rate 


For either device, the system clock interrupt service rou- 
tine is entered each time the clock ticks. 


Maintaining the System Time 


RT-11 maintains the time of day in two 16-bit words which 
indicate the time in terms of ticks past midnight. Unless 
you use the TIME command to set the time, the time the 
system displays represents the time that has elapsed since 
bootstrap. — 

The time is automatically reset after midnight under 
the FB monitor, but not under the SJ monitor unless this 
has been selected as a system generation option. 

Each pair of words used to represent the system time 
is considered as a 32-bit interger value. The first word holds 
the high-order part of the number and the second word the 
low-order part. This 32-bit format is referred to as the in- 
ternal format. In the following examples of MACRO—11 and 
FORTRAN IV code, the data area TIMER contains the in- 
ternal format representation for 60 seconds at 60 Hz (3600 
ticks). 
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od 


DATA TIMER/0,3600/ !3600 ticks 


j 

EXAMPLE 
: i 
MACRO-11 r 
TIMER: . .WORD 0,3600. 33600 ticks : 
FORTRAN IV | 
INTEGER*2 TIMERC2) 2 consecutive words 


Dacron neni wiasti entivi inns dee diane mac dace dina Sanna itd on nase ni 


| 
| 
| 
| 
| 
| 


Accessing the System Time 


A number of requests are available to programs to get the 
system time, either in internal format (ticks—high order first, 
low order second) or in hours, minutes, and seconds. 

The MACRO-11 request .GTIM returns the current 
system time in internal format and indicates the number of 
ticks since midnight (or since the last bootstrap). The for- 
mat of the request is: 


.GTIM — area,addr 


In this request, ‘‘area’”’ is the address of a two-word EMT 
argument block. Here ‘‘addr’”’ is the address of a two-word 
area in which the monitor stores the system time. The .GTIM 
request is described in chapter 2 of the RT—11 Program- 
mer’s Reference Manual. 

The FORTRAN IV subroutine GTIM is equivalent to the 
MACRO-11 .GTIM request. The format of the call is: 


CALL GTIM(itime) 


Here ‘‘itime”’ is a two-word area in which the system time 
is stored in internal format. - 

You can also use the SECNDS function to get the time. 
The function displays time as the number of seconds since 
midnight or a given time of day. The format of the function 
is: 
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time=SECNDS(sttim) 


In this function, “‘time’’ is a REAL*4 variable to store the 
returned value (in seconds); “‘sttim’’ is a REAL*4 expres- 
sion containing the start time, in seconds since midnight. 
If “‘sttim”’ is 0, the value returned is the current time of day 
(in seconds since midnight). 

The following example shows how you can find the 
execution time, in seconds, for a sequence of FORTRAN IV 
statements. 


The TIME subroutine returns the system time in hours, 
minutes, and seconds as an ASCII character string. 


You should note that the 24-hour clock is used; for exam- 
ple 1:00 p.m. is returned as 13:00:00. The format of the 
subroutine call is: 


CALL TIME(string) 


Here ‘‘string’’ is a variable or array eight bytes in length. In 
the following example, the FORTRAN IV code requests the 
current system time and prints it out at the terminal. 
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EXAMPLE 


1 REAL+8 STIME 'To hold system time 
CALL TIMECSTIME) !Get time in ASCII 

- & TYPE 100,STIME 

100 FORMAT (’ The time is ’,A8) | 


Fea ae senses tena inensien ah nh See sate acetennneoniiohaa Soman okt ah a mt bmaahin Ache AAs Rak RO AS CRE nts ae ih cates aN AMMA PMNS AHL 7 MUR MO AR RO SAE AS SA NR HO 


Three conversion routines are available to change cur- 
rent time or elapsed time from one format to another. 


¢ CVTTIM. Converts from internal time format to the 
integer number of hours, minutes, seconds, and ticks. 


¢ JTIME. Converts from the integer number of hours, 
minutes, seconds, and ticks to internal time format. 


¢ TIMASC. Converts from internal time format to 
ASCII character string in the format hh:mm:ss. 


Converting the System Time to 32-bit Integers 


The standard format for 32-bit integers under RT—11 is as 
follows: 


¢ -The low-order data is stored in the first word. 


e The high-order data is stored in the second word. 


The RT—11 internal time format is the reverse of this 
arrangement. You can use the JJCVT request to convert be- 
tween the two formats (in either direction), as follows: 


CALL JJCVT{(ivar) 


Here ‘‘ivar” is the INTEGER*4 variable whose high-order 
and low-order words are to be reversed. 

In order for the words to be printed in the correct or- 
der, you should call JJCVT to convert internal format sys- 
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tem times to standard 32-bit integer format before you use 
formatted I/O routines to print them out. In the following 
example the code gets the time of day (in internal format), 
converts it to standard RT—11 32-bit integer format, then 
prints it. 


_ 
| 
| 
i 
i 
| 
| 
} 
i 
| 
| 
| 
| 


a : : 
eee ee ee CRT eee ee eee 


EXAMPLE, ee 


Paecer TIME “tInternal format time . | 
~ CALL. GTIMCTIME) !Convert to INTEGER*#4 
CALL JJCVTCTIME) ee ee 
. -TYPE 10,TIME cae: 
on 10 FORMAT. ((* The clock has: ticked "419, eek 
ee Uo leeececos* times-s ince midnight.) 


i i ee GAR A aan ER ANNI. ut: NON NNSA i VON Ae LIOR AS clit BSB RE AS BME. eo oO HELE No hi oe tS th ieee 


A number of other routines for using 32-bit integers are 
available to FORTRAN IV programmers. See the PDP—11 
FORTRAN Language Reference Manual for RT—11 for ad- 
ditional information. 


Maintaining the System Date 


The RT—11 system date is stored in a single word. The 
month, day, and year are held in numeric format. To arrive 
at the number that represents the year, the system subtracts 
1972 from the current year. For example, the date May 30th, 
1983 would be stored as the following numbers: 


e Month 5 (must be in the range 1 to 12) 


e Day 30 (must be in the range 1 to the length of the 
month) 


e Year 11 (1983 minus 1972). 


The format of the ce system date word is shown in 
figure 71. 

The internal system date may be set or changed by any 
of the following events: 
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e The user issues the DATE monitor command to set 
the current date. 


e The date changes at midnight. However, RT—11 does 
not change the date until a job requests time of day 
with a .GTIM request. 


e The month and year values roll over. This occurs 
when month and year roll over has been selected at 
system generation time. 


e The DATE monitor command is issued to print the 
date. 


e A job issues a .SDTTM or ISDTTM request to change 
the system date (described later). 


Figure 71. 
Format of the System Date Word 


15 14 13 10 9 5 4 0 


Hoye MONTH (1-12) DAY (1-31) YEAR (MINUS 1972) 


Accessing the System Date 


A number of requests can be used in MACRO-11 and 
FORTRAN IV programs to access the system date and con- 
vert it to different formats. 


Accessing the system date from MACRO-11 programs 
To get the current system date in the internal format de- 
scribed above, issue the .DATE request, as follows: 


DATE 


This returns the date in RO. Notice that the system date does 
not change at midnight unless one of the events listed above 
occurs. To make sure that you get the correct date, it is rec- 
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ommended that you issue a .GTIM request before the .DDATE 
request. 


: ori “#AREA, #TIME : Get tne” 


DATE. ae tend date 


“Save date here ae : 


MOV pO DATE ;Save. current dates 


5 ai inns. cb obo anaes ng hbo god 


i Boe i ode a a ai bb ABS i dn OS Rn Oi EC tect 


Accessing the system date from FORTRAN IV programs 


The DATE subroutine gets the system date in ASCII for- 
mat, dd-mmm-yy. For example, 28-APR-84. The format of 
the call is: 


CALL DATE(date) 


In this call, ‘“‘date” is a variable or array at least nine bytes 
in length. If no system date has been set, ‘‘date’’ contains 
spaces on return from the subroutine. 


You can also get the month number, the day, and the 
last two digits of the year, with the IDATE subroutine. The 
format of the call is: 


CALL IDATE(month,day,year) 
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where all the arguments are INTEGER*2 variables. 


eNO LG a EN RR OR CN RENE RR MN I NNN NO NR CNOA UE NET AN NTC AR MOREE HM Mt NE aN 


EXAMPLE 


INTEGER*2 MONTH,DAY,YEAR 
CALL IDATECMONTH, DAY, YEAR) 


Fe ee ER LEE RS ae seat BONNE Ned a Mela inabesietnn nial edi neath iemiuibsindhta 


If today’s date is April 28, 1984, then after executing these 
statements, “MONTH” contains 4, “DAY” contains 28, and 
“YEAR” contains 84. If no system date has been set, these 
variables contain 0 on return from the subroutine. 

The DATE and IDATE subroutines can only be used 
in FORTRAN IV programs. 


Writing Programs Independent of Line 


Frequency 


Programs that use the system time and date normally de- 
pend on the frequency of the ac line supplying the hard- 
ware. You may want to write programs that perform com- 
putations based on time, but independent of the line 
frequency, for example, programs which will run on sys- 
tems in Europe as well as in the United States. 

At run time, your programs need to find out whether 
they are being run on a 50—Hz or 60—Hz system. This in- 
formation is held in the RMON configuration word (offset 
300 in the fixed offset area). 


Setting the System Time and Date 


You have seen that you can set the system time and date 
using the TIME and DATE monitor commands. You can also 
set them from your program using the following methods. 
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Setting the time and date from MACRO—11 programs 


To change the system time or date, issue the SSDTTM pro- 
grammed request as follows: 


.SDTTM _ area, addr 


In this request, ‘“‘area’”’ is the address of a two-word EMT 
argument block and ‘‘addr’’ is the address of a three-word 
block with the following contents: 


Word 1: The new date (internal format), or any 
negative number if you want to leave 
the date unchanged. 


Words 2 and 3: The new system time (internal format, 
with the high order in word 2, low or- 
der in word 3). Place any negative 
number in word 2 if you want to leave 
the time unchanged. 


Setting the time and date from FORTRAN IV programs 


The FORTRAN IV equivalent of the MACRO-11 .SDTTM 
request is ISDTTM. Another way of setting the system time 
and date from a FORTRAN IV program is to pass the TIME 
and DATE monitor commands to KMON when the pro- 
gram exits. To do this, use the SETCMD subroutine as de- 
scribed in chapter 10, “Controlling Program Execution.” If 
you want to set both the date and the time or pass any two 
or more monitor commands, then you should place these 
commands in an indirect file and pass the command to ex- 
ecute the file to KMON. 

A second method of setting the system date and time 
from a FORTRAN IV program is by calling a MACRO-11 
subroutine that issues the .SDTTM programmed request. 
Table 21 lists the requests and subroutines that access the 
system time and date. 


Mark-time Routines 


A mark-time routine is a subroutine that you request to be 
executed at a specific time of day, or after a specific period 
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Table 21. 

RT-11 Time and Date Requests 

Request Function FORTRAN IV MACRO-11 

.GTIM Get current time in . 
ticks since midnight 

GTIM Get current time in 7 * 
ticks since midnight 

SECNDS Get current or elapsed ee i 
time in seconds 

TIME Get time in ASCII format i . 

CVTTIM Convert internal time ‘i i“ 
to hrs,mins,secs,ticks 

JTIME Convert hrs,mins,secs, . 
ticks to internal time 

TIMASC Convert internal time id af 
to ASCII hh:mm:ss 

DATE Get date in internal 
format 

DATE Get date as ASCII string i 
in format dd-mmm-yy 

IDATE Get date as integer 7 
month,day,year 

SDTTM Set system date and 2 
time 

ISDTIM Set system date and ‘ : 


time 


of time has elapsed. Your program can issue programmed 
requests to schedule a mark-time routine to be run, and if 
you need, to cancel such requests. 

These requests are available only on systems that have 
timer service support. This feature is provided in all sys- 
tems under the FB or XM monitors, but it is a system gen- 
eration option under the SJ monitor. 

Mark-time routines run as completion routines. When 
you issue a mark-time request from a program, RMON builds 
a timer queue element, which is placed in the timer queue. 
This queue is managed by the same routines that serve clock 
interrupts. The elements in the queue are sorted by the time 
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at which they expire, with the element that expires first at 
the head of the queue. 

Each time a clock interrupt occurs, the clock service 
routine checks to see if there is a timer queue element whose: 
time limits have expired. If there is, it is removed from the 
timer queue and placed in the completion queue for the job 
that issued the mark-time request. 

Timer queue elements are taken from a pool of I/O — 
queue elements. Your ‘program must allocate at least as many 
queue elements as the number of mark-time and I/O re- 
quests that expect to be pending simultaneously. If you need 
to change the number, use the .QSET request (MACRO-—11) 
or the IQSET subroutine (FORTRAN IV) as described in 
chapter 15, “Using Nonsynchronous Queued Input/ 
Output.” When there are insufficient queue elements in the 
pool, the mark time request returns an error. 


Scheduling Mark-time Routines 


When you issue a mark time request, an entry is placed in 
the timer queue. You have to specify the address of the 
completion routine and the time that must elapse before the 
completion routine is to be run. Note that this is not the 
time of day at which the routine should be run. The time 
must be given as a number of ticks, in internal format (high- 
order word first, low-order word second). 

You also specify a nonzero identification number, or 
id number, for each mark-time request. It must not be in 
the range 177000 (octal) to 177777 (octal), as these num- 
bers are reserved for system use. The id number allows you 
to cancel specific mark time requests, as you will see later. 


‘Id numbers need not be unique; you may specify the same 


id number for more than one mark-time request. 


Issuing MACRO—11 mark-time requests 


You use the .MRKT programmed request to issue a mark 
time, as follows: 


.MRKT _area,time,crtn,id 
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area is the address of a four-word EMT argument 
block. 

time is the address of a 2-word area containing the 
time that must elapse (in ticks, internal for- 
mat). 

crtn is the entry point (start address) of the com- 


pletion routine (written in MACRO-11). 


id is the identification number. On entry to the 
completion routine, the id number is in RO. 


Since the expiration time is given in terms of ticks un- 
til the event, it is independent of the system time set by the 
monitor command TIME or the .SDTTM programmed re- 
quest. If you change the time of day, the expiration time of 
mark-time requests does not change. 

In the following example the MACRO-—11 code sched- 
ules the completion routine COMPL to be run after 3600 
ticks. 


EXAMPLE | | 


ELAPS: .WORD 0,3600. ;Elapsed time 
AREA:  .BLKW 4 ;EMT argument block 


ISSUE MARK TIME FOR 3600 TICKS, ID=4 
-MRKT... AREA, #ELAPS, #COMPL , #4 


COMPL: — ;Completion routine 


rn tree Rm NR SOI eS EN rent NNO GOREN 


Issuing FORTRAN IV mark-time requests 


FORTRAN IV programmers have a choice of three mark-time 
requests. Each of the functions returns a zero value to in- 
dicate a normal return, or nonzero if there are insufficient 
queue elements in the pool. The three functions are: 
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1. The MRKT function is equivalent to the MACRO-11 
-MRKT request. The format of the call is: 


IERR = MRKT(id,crtn,time) 


The completion routine must be written in MACRO— 
11 and specified in an EXTERNAL statement in the 
FORTRAN IV routine that issues the MRKT call. 
“time’’ is the period of time to pass until the routine 
is run. | 


2. The ITIMER function is similar to MRKT, except that 
the completion routine is written in FORTRAN IV, 
and the period of time to pass is specified in hours, 
minutes, seconds, and ticks. The format of the call is: 


IERR = ITIMER(hrs,mins,secs,ticks,area,id,crtn) 


3. The ISCHED function is similar to ITIMER, except 
that the time specified is the time of day at which the 
routine is to be run, not the period of time which is 
to elapse. The time is specified in hours, minutes, 
seconds, and ticks, and the completion routine is 
written in FORTRAN IV. The format of the call is: 


IERR = ISCHED(hrs,mins,secs,ticks,area,id,crtn) 
The arguments for these requests are as follows: 


id is a nonzero identification (id) number. 


crtn is the address of the completion routine. 
This routine may be written in MACRO-11 
or FORTRAN IV, depending on the request 
you use. The name of the routine must be 
specified in an EXTERNAL statement in the 
FORTRAN IV routine that issues the mark 
time request. 


area is the address of a four-word block in your 
program, similar to the one used in event- 
driven I/O. 

time is a time specified in internal RT—11 time 
format. 

hrs, mins, are integer numbers of hours, minutes, 


secs, ticks seconds, and ticks. 
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Cancelling Mark-time Requests 


You can write your programs so that you can cancel one or 
more scheduled mark-time requests if you detect certain 
conditions. To do so, use a programmed request that re- 
moves the timer queue elements from the timer queue. If a 
timer queue element has already expired and been‘trans- 
ferred to the completion queue, then you cannot cancel it. 

To cancel a specific mark-time request, you must 
specify the same id number you gave in the original mark- 
time request. If there is more than one element in the queue 
with the same id number, the one which is to expire first 
is cancelled. 

To cancel all the mark-time requests in the timer queue, 
you should specify an id number of 0. Notice that system 
mark-time requests, those with an id number in the range 
177000 (octal) to 177777 (octal), are not affected. If you 
specify a nonzero id number, you can supply another pa- 
rameter to the cancel mark-time request in which the mon- 
itor returns the amount of time remaining for the cancelled 
request. 


Cancelling MACRO—11 mark-time requests 


To cancel a mark time request, use the .CMKT request, as 
follows: 


.CMKT  area,id[,time] 


area is the address of a three-word EMT argument 
block. 
id is the identification number specified in the 


original mark time request, or 0 to cancel all re- 
maining mark time requests. 


time (optional) is the address of a two-word area in 
which the monitor returns the time remaining 
for the cancelled request (internal format: high- 
order word first, low-order word second). 


This request sets the C bit if there are no elements in 
the queue with the specified id. The following example 
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shows the code to cancel all mark-time requests with the 
id number 5. 


ieee etter ge ERT A NN AR SMS SETS RIA FEET TT I RECO G TE OETA MIME LEE LE ILE ELE LIE TE ESL ELE Sey 


: EXAMPLE a 


BCC Ate zs 


ae 


| SAS = OMKT —-BAREA, 4, #0 ;Cancel mark time. 


Sea ORE ORD Ce ane eres CREE or Ree TINE ORNS Ae POE PEC Se ee ee een oe Cn ee 


Cancelling FORTRAN IV mark-time requests 


Use the ICMKT function to cancel one or more mark-time 
requests, as follows: 


JERR = ICMKT(id,time) 


id is the identification number specified in the 
original mark time request, or 0 to cancel all re- | 
maining mark time requests. 


time is the name of a two-word area in which the 
monitor returns the time remaining for the can- 
celled request (internal format—high-order word 
first, low-order word second). 


The function returns a nonzero value if there is no element 
with the specified id in the timer queue. The following ex- 
ample shows the code to cancel all mark-time requests with 
the id number 5. 


= EXAMPLE eee : | 
eee ets INTEGER#4 “TLEFT. cee a a. 
: Ate STF Cokes, TLEFTD. EQ. 060. To 10 ee 


eee RC Or ee Meera ee ee ee Coe nen enero hats me eee ee SR eens Es aeece ee ea 


The value returned is 0, as long as there is an active re- 
quest with the specified id (5 in this example). 
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Periodic Scheduling 


Scheduling a routine to run periodically is a common ap- 
plication of the RT—11 mark-time requests. For example, you 
can schedule a routine to sample data regularly. The small- 
est time period you can use for sampling data is one clock 
tick. This is 16.67 millesecond for 60-Hz systems or 20 
millesecond for 50-Hz. 

In order to do periodic scheduling, you issue the mark- 
time request in the completion routine. This request places 
another entry in the timer queue each time you enter the 
routine. 


Designing Watchdog Routines 


In data acquisition applications it is often important to de- 
termine whether or not an I/O event has occurred within a 
critical period of time. For example, if an instrument in a 
nuclear plant is designed to generate an interrupt every two 
minutes, the computer monitoring system may have to take 
action if the expected interrupt fails to occur (device fail- 
ure). Routines that check for such events are called watch- 
dog routines. 

The sequence of steps involved in the general design 
scheme for a watchdog routine is: 


1. Issue an event-driven I/O request and a mark-time re- 
quest for an alarm routine. The-alarm routine is en- 
tered if the I/O request is not executed. 


2. In the completion routine for the event-driven I/O re- 
quest, cancel the mark-time request, issue a new 
event-driven I/O request, then issue a new mark-time 
request. 


3. If the event-driven I/O fails to occur, the alarm rou- 
tine scheduled by the mark-time request is entered. 
This routine should alert the operator, or take other 
measures such as turning off devices. 
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Timed Waits 


Programming with RT—11 


You may want to suspend execution of your program for a 
specified period of time if certain conditions occur. RT—11 
provides programmed requests to do this, but you can use 
them only if your system has timer service support. All of 
these requests need a timer queue element, so you have to 
count them when you determine the number of queue ele- 
ments to allocate to your program with .QSET or IQSET. 
These requests suspend execution of your main program 
only. Any completion routines from previous mark-time or 
nonsynchronous queued I/O requests continue to execute. 


Suspending execution of a MACRO—11 program 


To suspend execution of your program for a specified pe- 
riod of time, use the .TWAIT request as follows: 


-TWAIT  area,time 


Here ‘‘area” is the address of a two-word EMT argument 
block and ‘‘time”’ is a pointer to two words containing the 
time (in ticks) in internal format (high-order word first, low- 
order word second) for which the job is to be suspended. 
The following example shows program execution sus- 
pended for 5000 ticks. 


nest mnemonic mre te tn EEA MT EHTS ESR EY TI APO PE 


- EXAMPLE ~~ 
[2 TIMER WORD 05000. ;Time to wait a 
AREA: SBLKW 20S EMT argument block =~ 


,TWAIT #AREA,#TIME ;Suspend for S000. 
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Suspending execution of a FORTRAN IV program 


FORTRAN IV programmers can use any of three different 
requests to suspend program execution. Each function re- 
turns the value zero to indicate a normal return, or a non- 
zero value if no more queue elements are available: 
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1. The ITWAIT function is equivalent to the MACRO-11 
.TWAIT request. The format of the request is: 


IERR=ITWAIT(time) 


In this request, “time” is the two-word internal for- 
mat (high-order word first, low-order word second) 
time period for which the program is to be sus- 
pended. For example, the following code suspends 
program execution for 3600 ticks: 


INTEGER*2 TIME 
DATA TIME/0 ,3600/ 
IERR=ITWAITCTIME) 'Suspend program 


2. The ISLEEP function suspends job execution for a 
period of time specified in hours, minutes, seconds, 
and ticks. The format of the request is: 


IERR = ISLEEP(hrs,mins,secs,ticks) 


Here “‘hrs,mins,secs,ticks” are the integer numbers of 
hours, minutes, seconds, and ticks for which job exe- 
cution is to be suspended. For example, the follow- 
ing statement suspends program execution for three 
hours and five minutes: 


IERR=ISLEEPC3,5,0,0) 


3. The IUNTIL function suspends program execution 
until the specified time of day. The format of the re- 
quest is: 


IERR = IUNTIL(hrs,mins,secs,ticks) 


Here ‘“‘hrs,mins,secs,ticks” are integer numbers repre- 
senting the time of day at which the job is to start ex- 
ecution again. For example, the following statement 
suspends program execution, and starts execution 
again at 15:45:00: 


IERR=IUNTILC15,45,0,0) 


Table 22 lists the requests and subroutines that issue mark 
time requests and timed waits. | 
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Practice You can do this exercise only if your computer has a sys- 
20—1 tem clock and timer service support. 


1. Write a program, in MACRO-11 or FORTRAN IV, to 
perform the following: 


a. Get the system time and date. If the date has not 
been set, the program exits, printing a message ask- 
ing the operator to set the date and time. If the 
date has been set, the program displays the current 
time and date, and continues to step b. 


Allocate enough queue elements for the remainder 
of the program, and set up a completion routine to 
run for 20 seconds. The completion routine should 
set a flag to indicate that it has run. If the request 
to set up the completion routine fails, print an er- 
ror message and exit; otherwise go to step c. 


Test to see whether the completion routine has 
run. If it has, go to step e. Otherwise display the 
message: 


Type as much as you can in 2 seconds, starting 
now: 


Enable terminal special mode and error returns for 
terminal I/O (bits 12 and 6 of the JSW). Then wait 
for 2 seconds. 


When 2 seconds have passed, read all the charac- 
ters in the I/O buffer, and print out the message: 


You managed to type: 
followed by the input text. Then go to step e. 


Get and display. the current time and date, then 
exit. 


Test your program. See how many characters you can 
type in during each cycle. Check that the program 
times out after 20 seconds. 
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Table 22. 

RT-11 Mark-time and Time-wait Requests 

Request Function FORTRAN IV. MACRO-11 

-MRKT Mark time for period ” 
(internal format) 

MRKT Mark time for period ‘ 
(internal format) 

ITIMER Mark time for period 2 4 
(hrs,mins,secs,ticks) 

ISCHED Mark time until time : si 
of day (hrs,mins,..) 

.CMKT Cancel one or all a‘ 

_ mark-time requests 

ICMKT Cancel one or all , . 
mark-time requests 

-TWAIT Wait for timeout period 2 
(internal format) 

ITWAIT Wait for timed period : . 
(internal format) 

ISLEEP Wait for timed period ‘ . 
(hrs,mins,secs, ticks) 

IUNTIL Wait until given time i F 


of day (hrs,mins,..) 
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Solutions to Practices 


CHAPTER 10 


10-1. MACRO-11 
-EDIT/CREATE PR1001.MAC 
-EDIT/CREATE PR1002.MAC 
-MACRO PR1001 

«LINK PR1001 


»-RUN PR1001 
Enter command: DATE 01-JUN-84 


»~REENTER 
2?KMON-F-Invalid command 


-EDIT/OUTPUT:PR1003.MAC PR1001.MAC 
-TITLE PR1003 


; PR1003 Prompt the user to enter a command, read 
; it, and exit allowing reentry. On REENTER 
; chain to PR1004 passing the input command 
7 as data. 


-MCALL .GTLIN .PRINT .PEEK -POKE 
-MCALL .CHAIN .EXIT 
»-ENABL LC 

AREA: .» BLKW 3 ;EMT argument block 
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; The data in between PRG2 and the end of MSGBFR 
3; will be copied into the communication region 
s Clocations S00 onwards). 


PRG2: -RADSO 
' .RADSO 
-RADSO 
MSGBFR: .REPT 
- WORD 
-ENDR 
PROMPT: .ASCII 
REWIND: .ASCIZ 
-EVEN 
JSW 
REENTR 
BR 
START: .GTLIN 


«PRINT 
- PEEK 
MOV 
BIS 
»PQKE 
MOV 
-EXIT 


/DK / ;File specification 
7PR1004/ ;for the CHAIN request 
/SAV/ 

41 ;Message buffer 

0 ; Czeroed) 


"Enter command: "<200> 
“REENTER the program" 


= 44 ;JO0B STATUS WORD 
7 20000 ;REENTER BIT €13) 
ENTRY2 ;sREENTRY POINT 


#MSGBFR,#PROMPT ;Prompt and place 
; input into MSGBFR 


#REWIND ;Remind user to REENTER 
#AREA, #JSW ;Get the JSW 
RO,R1 ;Set REENTER. allowed 
*REENTR,R1 ; bit in the JSW 
#AREA, #JSW,R1 
#1,R0 ;Exit with REENTER 

; enabled 


; PART 2 When program exits, REENTER it. Chain 
: to the next program CPR1004). 


ENTRY2: MOV 
MOV 

20$: -POKE 
TST 
TST 
BNE 
- CHAIN 
- END 


-MACRO PR1003 
»-LINK PR1003 
~-MACRO PR1002 


-LINK PR1002 


»RUN PR1003 


#500,R1 sLoad info area addr 
#PRG2,R2 sLoad data buffer addr 
#AREA,R1,CR2) ;Move command string 


CR1)+ ; into CHAIN area 
CR2)+ ; and advance pointers 
20$ ;Branch until done 

;CHAIN to next program 
START 


Enter command: DATE 01-JUN-83 
REENTER the program 


-REENTER 


HI THERE! THIS IS PROGRAM 2. 
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-EDIT/OUTPUT:PR1004.MAC PR1002.MAC 
-TITLE PR1004 

; PR1004 Announce that program 2 has started. See 

; if program was chained to. If not print 


: an error message and exit. Otherwise, 
4 pass the command from the chain buffer to 


: KMON. 
’ 
-MCALL .PRINT .PEEK -POKE ~-EXIT 
»-ENABL LC 
AREA: -BLKW 3 sEMT Argument block 
MSGLEN: .WORD 0 ;Command string length 
CMDSTR: .BLKW 41. ;Command string buffer 
HELLO: .ASCIZ “HI THERE! THIS IS PROGRAM 2." 
NOTCH: .ASCIZ “** NOT CHAINED TO **" 
» EVEN 
JSW = 44 ; JOB STATUS WORD 
CHAIN = 400 ; CHAIN BIT (8) 
KMON = 4000 ; KMON CMMD BIT (11) 
START: .PRINT #HELLO ;Display message 
. PEEK #AREA, #JSW 3;Get JSW 
MOV RO,R3 ;Save JSW 
BIT #CHAIN,R3 ;Were we chained to? 
BEQ STOP sBranch if not Cerror) 
3* 
3 We were chained to and the command for KMON tis 
; in the CHAIN AREA, but in the wrong format. 
7 Retrieve the command from the chain area and 
; restore it inserting the string length as the 
5 first word. Then set JSW bit 11 and RO to 0 
‘ to give the command line to KMON on EXIT. 
MOV #510,R1 s;Load CHAIN AREA addr 
MoV *#CMDSTR,R2 ;Buffer to receive data 
10$ -PEEK *#AREA,R1 ;Copy data from CHAIN 
TST CR1)+ ; area into receive 
MOV RO, CR2)+ ; data buffer 
BNE 10$ ;Repeat until done 
TST -CR2) ;Step back to string 
20$: TSTB -CR2) ;Was previous byte zero? 
BEQ 20$ ;Branch if so 
SUB *CMDSTR-2,R2 ;Calculate & save string 
MoV R2,MSGLEN 3; length Cwith null) 
MOV #510,R1 sLoad CHAIN AREA address 
MOV #MSGLEN,R2 ;Load command string addr 
-30$: ~POKE #AREA,R1,CR2) ;Copy data into CHAIN 
TST CR1)+ 3; area from buffer 
TST CR2)+ 
BNE 30$ ;Repeat until done 
BIS #KMON,R3 3;Set KMON command bit 
~PQKE #AREA, #JSW,R3 3; in JSW 
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CLR RO i s;Clear RO for exit 
~-EXIT sExit 
STOP: -PRINT #NOTCH ;Issue not chained msg 
- ~-EXIT sAnd exit 


- END START 


-MACRO PR1004 

-LINK PR1004 

-RUN PR1004 

HI THERE! THIS IS PROGRAM 2. 
** NOT CHAINED TO ** 

-EDIT PR1003.MAC 

-MACRO PR1003 

-LINK PR1003 

-RUN PR1003 

Enter command: DATE 11-JUN-84 
REENTER the program 


-REENTER 
HI THERE! THIS IS PROGRAM 2. 


-DATE 
11-Jun-83 


-RUN PR1003 
Enter command: DATE 10-JUN-83 
REENTER the program 


-REENTER 
HI THERE! THIS IS PROGRAM 2. 


-DATE 
10-Jun-83 
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10-2. FORTRAN IV 


-EDIT/CREATE °PR1001.FOR 
-EDIT/CREATE PR1002.FOR 

-FORTRAN PR1001 

-LINK PR1001,SY:FORLIB 


»-RUN PR1001 
Enter command: DATE 01-JUN-84 


STOP -- END OF PROGRAM 
-EDIT PR1001.FOR 
«FORTRAN PR1001 

-LINK PR1001,SY:FORLIB 


-RUN PR1001 
Enter command: DATE 01-JUN-84 


-EDIT/OQUTPUT:PR1003.FOR PR1001.FOR 


PROGRAM PR1003 


Cc 
Cc Prompt the user to enter a monitor command. 
Cc Chain to program 2 and pass the command to it. 
Cc A zero byte is added to the command string read 
Cc Cnote that the 80th character may be lost). 7 
Cc 
BYTE MSGBFR(80) 
REAL*8 FIDBLK ! FILE DESCRIPTOR BLOCK 
DATA FIDBLK /12RDK PR1004SAV/ 
TYPE 100 ! PROMPT FOR A COMMAND 
100 FORMAT C1H$,’Enter command: ’) 
ACCEPT 101,ICHARS,MSGBFR ! READ A COMMAND 
101 FORMAT C€Q,80A1)2 
IF CICHARS .EQ@. 80) ICHARS=79 
MSGBFRCICHARS+1)=0 ! ADD STRING TERMINATOR 
CALL CHAINCFIDBLK,MSGBFR,40) 
CALL EXIT ! EXIT AND CHAIN 
END 


-FORTRAN PR1003 
-LINK PR1003,SY:FORLIB 
-FORTRAN PR1002 


-LINK PR1002,SY:FORLIB 
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-RUN PR1003 
Enter command: DATE 01-JUN-84 
HI THERE! THIS IS PROGRAM 2. 


-EDIT/OUTPUT:PR1004.FOR PR1002.FOR 


PROGRAM PR1004 


ANNOUNCE PROGRAM 


Cc 
Cc Announce that program 2 has started. Request 
c chain information. If program was chained to 
C by another program setup to have KMON execute 
C the passed command and exit to execute command. 
C Otherwise, issue an error message. 
Cc 

BYTE MSGBFRC80) 

TYPE 100 ! 
100 FORMAT C1H ,’HI THERE! 


THIS IS PROGRAM 2.7) 


CALL RCHAINCICHAIN,MSGBFR, 40) 
“** NOT CHAINED TO **’ 


IF CICHAIN .EQ. 0) STOP 


CALL SETCMDCMSGBFR) 
CALL EXIT 
END 
-FORTRAN PR1004 
e-LINK PR1004,SY:FORLIB 
-RUN PR1004 
HI THERE! THIS IS PROGRAM 2. 
STOP ~- ** NOT CHAINED TO ** 
-EDIT PR1003.FOR 
-FORTRAN PR1003 
«LINK PR1003,SY:FORLIB 
-RUN PR1003 
Enter command: DATE 01-JUN-84 


HI THERE! THIS IS PROGRAM 2. 


- DATE 
1-Jun-84 


»-RUN PR1003 
Enter command: DATE 10-JUN-84 
HI THERE! THIS IS PROGRAM 2. 


- DATE 
10-Jun-84 


PASS COMMAND TO KMON 
EXIT 


Solutions to Practices 


CHAPTER 12 


12-1. (Step 1) MACRO-11 


-EDIT/CREATE PR1202.MAC 


- TITLE 
«MCCALL .TTYIN 
*MCALL .EXIT 


H Data Defintions 
AREA: »BLKW 3 


277 


PR1202 -- TERMINAL I/0 EXERCISE 
-TTYOUT .TTINR .PEEK ~-POKE 


;EMT ‘argument block 


;Input buffer 


;Point to prompt buffer 
sPrint Cw/wait) 1 char 
;End of message? 

;Loop if not 

;Point to input buffer 
sLoad maximum char count 
;Read Cw/wait) 1 char 
;Decrement char count 
;Branch if buffer full 
;Was character a <CR>? 
;Branch if not 

;Yes, store null byte 
sGet <LF> char 


PROMPT: .ASCIZ “Please type in your name: " 
OUT: -ASCII “Welcome to RT-11, ™ 
MSGBFR: .BLKB 80. 
»-EVEN 
s Program Code 
START: MOV #PROMPT,R1 
10$; -TTYOUT CR1)+ 
TSTB CR1) 
BNE 10$ 
MOV #*MSGBFR,R1 
MOV #80.,R2 
GET: -TTYIN CR19+ 
“DEC R2 
BEQ OFLO 
CMPB #15,R0 
BNE GET 
LINE: CLRB -1¢€R1) 
-TTYIN 
BR PRINT 


; Buffer full. 


OFLO: CLRB -CR1) 
-PEEK AREA, #44 
MOV RO,R1 
BIS #100,R1 
-POKE #AREA,#44,R1 
10$: -TTINR 
BCC 10$ 
-PEEK *AREA, #44 
MOV RO,R1 
BIC #100,R1 
-POKE #AREA, #44,R1 
PRINT: MOV *“OUT,R1 
10$; -TTYOUT CR1)+ 
TSTB CR1) 
BNE 10$ 
-TTYOUT #15 
-TTYOUT #12 
~EXIT 


END START 


;Otherwise, print 


Flush terminal input buffer 


;Append null byte 

3;Get JSW 

sMove to R1 

sInhibit TT wait 
;Update JSW 

s;Read Cwo/wait) 1 char 
;Branch if char read 
3Get JSW 

sMove to R1 

sEnable TT wait 
;Update JSW 

sLoad buffer address 
;Print Cw/wait) 1 char 
;I1s next byte null? 
sBranch if not 
;Otherwise print <CR> 
3; and <LF> 

sExit 
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-MACRD PR1202 


eLINK PR1202 


«RUN PR1202 
Please type in your name: USER’S NAME 
Welcome to RT-11, User’s Name 


12-1. (Step 2) MACRO-11 


»-EDIT/CREATE PR1203.MAC 


AREA: 
PROMPT: 
MSGBFR: 


START: 


10$: 


GET: 


10$: 


OFLO: 


.TITLE PR1203 -- TERMINAL I/O EXERCISE 
-MCALL .TTYIN .TTYOUT .TTINR .PEEK -POKE 
-MCALL .EXIT 

Data Defintions 


.» BLKW 3 ;EMT argument block 
-ASCIZ <¢15><12>"Enter message: ” 

»BLKB 80. sInput buffer 

- EVEN 

Program Code 

-PEEK #AREA,#44 ;Get JSW 

MOV RO,R3 sMove to R3 

BIC #10000,R3 ;Enter normal mode input 
-POKE #AREA,#44,R3 ;Update JSW 

MOV #PROMPT,R1 sPoint to prompt buffer 
-TTYGUT CR1>+ sPrint Cw/wait) 1 char 
TSTB CR1) sEnd of message? 

BNE 10$ sloop if not 

MOV #MSGBFR,R1 sPoint to input buffer 
MOV #80.,R2 sLoad maximum char count 
-TTYIN CR1)+ ;Read Cw/wait) 1 char 
DEC R2 3;Decrement char count 
BEQ OFLO sBranch if buffer full 
CMPB #1S,R0 sWas char a <CR>? 

BNE GET ;Branch if not 

CLRB -CR1) 3Yes, store null byte 
~TTYIN 3sGet <LF> char 

cMP #MSGBFR,R1 § ;Empty line? 

BNE 10$ ;Branch if not 

-EXIT ;Otherwise, exit 

MOV #80.,R2 3No, set line length = 80. 
- PEEK #AREA, #44 3Get JSW 

MOV RO,R3 sMove to R3 

BIS #10000,R3 3;Enter special input mode 
»POKE #AREA, #44,R3 3;Update JSW 

BR OUTSET ;Branch to print cycle 
Buffer full. Flush terminal input buffer 

. PEEK #AREA, #44 7Get JSW 

MOV RO,R3 sMove to R1 


BIS #100,R3 sInhibit TT wait 


10$: 


OUTSET: 
LOOP: 


NIL: 


10$: 


NOIN: 


108; 
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-POKE #AREA, #44,R3 
»TTINR 


BCC 10$ 

-PEEK #AREA, 444 
MoV RO,R3 

BIC #100,R3 
-POKE #AREA, 444,R3 
MOV #80.,R2 

MOV *#MSGBFR,R1 
«PEEK #AREA, #44 
Mov RO,R3 

BIS #100,R3 


-POKE #AREA, #44,R3 
CLR R4 


«TTINR 

BCS NIL 

MOV RO,R4 
-PEEK #AREA, #44 
MoV RO,R3 
BIC #100,R3 
-POKE #AREA, #44,R3 
TST R4 

BEQ NOIN 
CMPB #32,R4 
BNE 10$ 

JMP START 
CMPB #15,R4 
BEG Loop 
CMPB #12,R4 
BNE NOIN 
JMP START 
-TTYOUT CR1)+ 
DEC R2 

‘BNE 10$ 
»TTYOUT #15 
-TTYOUT #12. 
MoV #80.,R2 
TSTB CR1) 
BEQ OUTSET 
BR LOOP 


- END START 


-EXECUTE PR1203.MAC 


Enter message: THIS 


IS A TEST. 


;Update JSW 

sRead Cwo/wait) 1 char 
;Branch if char read 
3Get JSW 

sMove to Ri 

sEnable TT wait 
sUpdate JSW 

;Set line length = 80. 
;Point to buffer 
3Get JSW 

Move to R3 

sInhibit TT wait 
;Update JSW 

3R4 = 0 for NO INPUT 
;Try to read a char 
;Branch if no input 
;Save input char 
3Get the JSW 

sMove to R3 

;Enable TT wait 
sUpdate JSW 

sAny input? 

;Branch if not 

sWas it “2? 

3;Branch if not 

3Yes, restart 

sWas it <CR>? 


;Branch if so, get <LF»> 


sWas it <LF>? 


3;Branch if no, NO INPUT 


3Yes, restart 

sPrint Cw/wait)d 1 char 
;Decrement counter 
3Branch if not at end 
;Otherwise print <CR> 
3 and <LF> 

;Reset counter to 80. 
sEnd of text buffer? 
sBranch if so 

3No, continue 
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THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS| 
IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A 
TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST. 
THIS IS A TEST.THIS' IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS 
IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A 


TEST.THIS 
THIS IS A 


Enter message: SECOND LINE. 
SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND .LINE.SECOND L 
INE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECO 
ND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SE 
Enter message: 


IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST. 
TEST.THIS IS A TEST.THIS IS 
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12-1. (Step 1) FORTRAN IV 


-EDIT/CREATE PR1202.FO0R 


OQ 


130 
150 
151 


PROGRAM PR1202 


BYTE PROMPTC80) ! PROMPT OUTPUT BUFFER 
BYTE MSGBFRC 100) ! INPUT MESSAGE BUFFER 
BYTE MSGOUTC118) ! OUTPUT MESSAGE BUFFER 


CALL SCOPYC’Please type in your name: “ PROMPT) 
Output prompt. 

DO 10,1#1,80 

IF CPROMPTCI) .EQ@. 0) GO TO 20 


IF CITTOURCPROMPTCI)) .NE. 02 GO TO S 
CONTINUE 


Now input user’s name. 


DO 40 1=1,100 | 
IERR=ITTINRO) ! ACCEPT CHAR 


IF CIERR .LT. 02 GO TO 25 ! LOOP UNTIL READ 
MSGBFRCI)=I1ERR ! STORE CHAR IN BUFFER 
IF CMSGBFRC(I) .NE. "15) GO TO 40 

MSGBFRC1)=0 ! CHANGE <CR> TO NULL 
IF CITTINRO) .LT. 0) GO TO 30 ! ACCEPT <LF> 

GO TO 100 

CONTINUE 


Buffer overflowed (more than 100 chars typed) 
Read & lose remaining chars in input buffer. 


CALL IPOKEC"44, IPEEKC"44).0R.%100) 

IF CITTINRCD .GE. 09 GO TO 6S 

CALL IPOKEC'44,IPEEKC"44) .AND. .NOT. 100) 
MSGBFRC100)=0 


Concatenate message with user’s name. 


CALL CONCATC’Welcome to RT-11, ’,MSGBFR;MSGOUT) 
DO 130 1=1,118 

IF CMSGOUTCI) .EQ. 0) GO TO 150 
IERR=ITTOURCMSGOUTCI)) ! OUTPUT A CHAR 

IF CIERR .NE. 0) GO TO 110 ! LOOP UNTIL OUTPUT 
CONTINUE | 4 

IF CITTOURC"1S5) .NE. 02 GO TO 150 ! OUTPUT <CR> 
IF CITTOURC"12) .NE. 02 GO TO 151 ! AND <LF> 
CALL EXIT 1 EXIT 

END 


-FORTRAN PR1202 


-LINK PR1202,SY:FORLIB 
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-RUN PR1202 
Please type in your name: <USER‘’S NAME> 
Welcome to RT-11, <User’s Name> 


»RUN PR1202 
Please type in your name: JOHN Q@. PUBLIC 
Welcome to RT-11, JOHN Q@. PUBLIC 


12-1. (Step 2) FORTRAN IV 


-EDIT/CREATE PR1203.FOR 


aoanananananananna 


- O20 0 


30 


Q0oa a 


PROGRAM PR1203 


Ask the user to type a message terminated by <CR»>. 
Qutput the message until the user types Control/Z 
or <CR>. Then ask for another message. Stop if 

a blank line is entered. Display 80 characters 
per line wrapping the rest of the message onto the 
following line as needed. 


BYTE PROMPTC80) ! OUTPUT BUFFER 
BYTE MSGBFRC80) ! INPUT BUFFER 
BYTE CRLFC3) 

DATA CRLF /15,%12,0/ 


Start of program, output the prompt. 


CALL IPOKEC'44, IPEEKC"44) .AND. .NOT. 10000) 
CALL CONCATCCRLF,’Enter message: ‘’,MSGBFR) 

CALL SCOPYCMSGBFR,PROMPT) ! BUILD PROMPT MESSAGE 
DO 10 I=1,80 

IF CPROMPTCI) .E@. 0) GO TO 20 

IF CITTOURCPROMPTCI)) .NE. 09 GO TO 5S 

CONTINUE 


Now input a message terminated by a <CR>. 


DO 40 11,80 


TERR#ITTINRO) ! ACCEPT A CHAR 

IF CIERR .LT. 02 GO TO 25 ! LOOP UNTIL READ 
MSGBFRCI)=IERR ! STORE CHAR IN BUFFER 
IF CMSGBFRCI) .NE. "15) GO TO 40! TEST FOR <CR> 
MSGBFRC1I)=0 ! CHANGE <CR> TO NULL 
TERR*ITTINRCO) ! ACCEPT AND LOSE <LF> 
IF CIERR .LT. 02 GO TO 30 

GO TO 100 

CONTINUE 


Buffer overflow (more than 80 characters). 
Read & lose remaining chars in input buffer. 
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60 CALL IPOKEC"44,IPEEKC"44) .OR. "100) 

6S IF CITTINRG) .GE. 0) GO TO 65S 
CALL IPOKEC'44,IPEEKC("44) .AND. .NOT. 100) 
MSGBFRC100)=0 ! MARK END OF BUFFER 

Cc 

Cc Now ready to output message from MSGBFR. 

Cc 

100 IF (MSGBFRC1) .EQ. 0) GO TO 150 ! EXIT IF BLANK 
CALL IPOKEC"44,IPEEK("44) .OR. "100009 
ICHAR=1 ! POINT TO MESSAGE START 

110 DO 130 I=1,80 

V15 CALL IPOKEC'44, IPEEKC("44) .OR. 100) 
IERR#*ITTINRC)D 


CALL IPOKEC"44,IPEEKC("44) .AND. .NOT. 100) 
IF CIERR .LT. 0) GO TO 120 


c 
Cc Deal with character just read. 
Cc 
IF CIERR .EQ@. "32) GO TO 1 ! CNTRL/Z, RESTART 
IF CIERR .EQ@. "15) GO TO 115 § <CR>, GET <LF> 
IF CIERR .EQ@. "12) GO TO.1 ! <LF>, RESTART 
120 IERR=ITTOURCMSGBFRCICHAR)) ! OUTPUT NEXT CHAR 
IF CIERR .NE. 0) GO TO 120 
ICHAR=ICHAR+1 
IF CMSGBFRCICHAR) .EQ@. 0) ICHAR=1 
130 CONTINUE 
131 IF CITTOURC"15) .NE. 02 GO TO 131 
132 IF CITTOURC"12) .NE. 0) GO TO 132 
GO TO 110 
C 
Cc Exit. 
c 
150 CALL EXIT 
END 


eEXECUTE PR1203.FOR/LINKLIBRARY:SY:FORLIB 


Enter message: THIS IS A TEST. 
THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS 
IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A 
TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST. 
THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS 
IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A 
TEST.THIS IS A TEST.THIS IS A TEST.THIS IS A TEST.THI 

Enter message: SECOND LINE. 

SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND L 
INE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECO 
ND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE. 
SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND L 
INE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECOND LINE.SECO 
ND LINE.SECOND LINE.SECOND 

Enter message: 
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12-2. MACRO-11 


-EDIT/CREATE PR1204.MAC 


AREA: 
PROMPT: 
MSGBFR: 


START: 


LOOP: 


10$: 


NOIN: 


STOP: 


- TITLE 
»-MCALL 
-MCALL 


PR1204 
-GTLIN 


Data Definitions 


- BLKW 
-ASCII 
-BLKB 
EVEN 
Program 
PEEK 
MOV 
BIC 
-POKE 
«RCTRLC 
-GTLIN 
TSTB 
BEQ 
PEEK 
mov 
BIS 
-POKE 
. PEEK 
MoV 
BIS 
«-POKE 
CLR 

- TTINR 
BCS 
mov 

» PEEK 
MOV 
BIC 
-POKE 
TST 
BEQ 
CMPB 
BEQ 
CMPB 
BEG 
CMPB 
BEG 
«PRINT 
BR 
-EXIT 
«END 


3 


“Enter message: 


80. 


Code 

#AREA, #44 
RO,R1 
#10000,R1 
#AREA, #44,R1 


#MSGBFR, #PROMPT 


MSGBFR 
STOP 
#AREA, #44 
RO,R1 
#10000,R1 


#AREA, #44,R1 


#AREA, #44 
RO,R1 
#100,R1 
#AREA, #44,R1 
R4 


10$ 

RO,R4 
#AREA, #44 
RO,R1 
#100,R1 
#AREA, #44,R1 
R4 

NOIN 
#32,R4 
START 
#15,R4 
LOOP 
#12,R4 
START 
#MSGBFR 
LOOP 


START 


-- TERMINAL I/O EXERCISE 
-PRINT 
-RCTRLO .EXIT 


-TTINR .PEEK -POKE 


;EMT argument block 


"<200> 


;Input buffer 


sGet JSW 

;Save value 

;Enter normal input mode 
;Update JSW 

sReset Control/O 

;Prompt & get input line 
;Null input line? 
sBranch if so 

3Get JSW 

s;Save value 

;Enter special input mode 
;Update JSW 

3;Get JSW 

;Save value 

sInhibit TT wait 

;Update JSW 

;Assume no char read 
;Read a char 

s;Branch if none available 
3;Save char 
sGet JSW 

;Save value 
sEnable TT wait 
;Update JSW 
;Any input? 
;Branch if not 
sControl/Z? 
sBranch if so, 
5<CR>? 

sBranch if so, 
3<LF>? 

s;Branch if so, 
;Print message 
sContinue 
sExit 


restart 


read <LF»> 


restart 
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EXECUTE PR1204.MAC 
Enter message: THIS IS A TEST. 


THIS 
THIS 
THIS 
THIS 
THIS 
THIS 


Is 
Is 
IS 
Is 
IS 
IS 


A TEST. 
A TEST. 
A TEST. 
A TEST. 
A TEST. 
A TEST. 


Enter message: SECOND LINE. 
SECOND 
SECOND 
SECOND 
SECOND 
SECOND 
SECOND 
SECOND 
SECOND 
Enter message: 


LINE. 
LINE. 
LINE. 
LINE. 
LINE. 
LINE. 
LINE. 
LINE. 


12-2. FORTRAN IV 


-EDIT/CREATE PR1204.FOR 


qoananaaan 


2-000 


- O00 


PROGRAM PR1204 


Ask the user to type a message terminated by <CR>. 
Output the message until the user types Control/Z 
or <CR>. Then ask for another message. Stop if 
a blank line is entered. Display each message on 
a new line. 


BYTE MSGBFR(80) ! INPUT MESSAGE BUFFER 
Start of program, output the prompt. 


CALL IPOKEC"44,IPEEKC"44) .AND. .NOT. ™10000) 
CALL RCTRLO 

CALL GTLINCMSGBFR,’Enter-message: ’) 

IF CMSGBFRC1) .E@. 0) GO TO 150 ! EXIT IF BLANK 
CALL IPOKEC'44, IPEEKC"44) -.OR. 10000) 


Output message until <CR>'or Control/Z typed. 


CALL IPOKEC'44,IPEEKC"44) .OR. 100) 
IERR=ITTINRC) 

CALL IPOKEC'44,IPEEKC"44) .AND. .NOT. 100) 
IF CIERR .LT. 0) GO TO 120 
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Deal with character just read. 


IF CIERR .EQ@. "32) GO TO 1 ! CNTRL/Z, RESTART 
IF CIERR .EQ@. "15) GO TO 115 ! <CR>, GET <LF> 
IF CIERR .EQ@. "12) GO TO 1 ! <LF>, RESTART 
CALL PRINTCMSGBFR) 


GO TO 115 
Exit. 
CALL EXIT 
END 


-EXECUTE PR1204.FOR/LINKLIBRARY:SY:FORLIB 
Enter message: 


THIS 
THIS 
THIS 
THIS 
THIS 


IS 
IS 
IS 
IS 
IS 


A TEST. 
A TEST. 
A TEST.) 
A TEST. 
A TEST. 


Enter message: 
SECOND 
SECOND 
SECOND 
SECOND 
SECOND: 
SECOND 
SECOND 
‘Enter message: 


LINE. 
LINE. 
LINE. 
LINE. 
LINE. 
LINE. 
LINE. 
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CHAPTER 13 


13-1. MACRO-11 
-EDIT/CREATE PR1301.MAC 
-TITLE PR1301 -- MULTITERMINAL I/O EXERCISE 


-MCALL .GTLIN .MTSTAT .MTATCH .MTGET .MTSET 
-MCALL .MTRCTO .MTPRNT .MTIN -MTDTCH .PRINT 


-MCALL 


EXIT 


Data Definitions 


-ENABL LC sEnable lower case 
WHICH: .ASCII “Which terminal do you want to use” 
-ASCIY ™ €1-7) 2? "<200> 
ERR1: -ASCIZ2 “** Attach Failure **" 
ERR2: -ASCIZ “** No Multiterminal Support **" 
WHO: -ASCIZ “Who are you? ™ ;Prompt text 


REPLY: .ASCII 


"Welcome to Multiterminal RT-11, " 


MSGBFR: .BLKB 81. ;Input buffer 
- EVEN 
AREA: .- BLKW 4 ;EMT argument block 
STAT: .» BLKW 8. sMT status block 
TSB: .» BLKW 4 sTtTerminal status block 
M.NLUN = 4 sOffset to # of terms 
;: Program Code 
START: MOV #STAT,R3 ;Status buffer 
-MTSTAT #AREA,R3 3;Get MT status 
TST M.NLUNCR3) ;How many terminals? 
BEQ NOMTY : s;Branch if none Cno MT) 
10$: -GTLIN #MSGBFR,#WHICH 3;Ask for terminal lun 
TSTB MSGBFR+ 1 sMore than one char? 
BNE 10$ ;Branch if so, repeat 
MOVB MSGBFR,R1 sMove char into R1 
CMPB #°0,R1 sCheck for numeric char 
BGT 10$ ;Branch if out of range 
CMPB #°7,R1 sCheck for numeric char 
BLT 10$ ;Branch if out of range 
BICB #/0,R1 s;ASCII --> binary 
BEQ STOP sExit if lun = 0 
-MTATCH #AREA, #0,R1 sAttach terminal 
BCC ATT ;Branch if success 
-PRINT #ERR1 sOtherwise, error 
BR 10$ 3;And try another 
ATT: -MTGET #AREA,#TSB,R1 sGet terminal status 
BIS #40000,TSB sEnable lower case 1/0 
-MTSET #AREA,#TSB,R1 ;Set terminal status 
-MTRCTO #AREA,R1 ;Reset CTRL/O to update 
-MTPRNT #AREA,#WHO,R1 ;Display prompt 
MOV #MSGBFR,R2 3;Point to input buffer 
GET: -MTIN #AREA,R2,R1 3;Get a char 
CMPB #15,CR2)+ sIs it <CR>? 
BNE GET sBranch if not 
CLRB -CR2) ;Yes, store null byte 
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-MTPRNT #AREA,#REPLY,R1 ;Print response 


-MTDTCH #AREA,R1 sDetach terminal 
STOP: ~-EXIT sExit 
NOMTY: -PRINT #ERR2 3No MT support error 
EXIT sExit 


- END START 


-MACRO PR1301 


-LINK PR1301 


-SHOW TERMINALS 


Unit Owner Type WIDTH TAB CRLF FORM SCOPE SPEED 
0 Local DL 80 No Yes No Yes N/A 
1 Local DL 80 No Yes No No N/A 
2 S-Console DL 80 Yes Yes No Yes N/A 
-RUN PR1301 


Which terminal do you want to use €1-7) ? 2 
Who are you? 

The user. 

Welcome to Multiterminal RT-11, The user. 


-RUN PR1301 

Which terminal do you want to use (1-7) ? 3 
** Attach Failure ** 

Which terminal do you want to use €1-7) ? 2 
Who are you? 

Ann 

Welcome to Multiterminal RT-11, Ann 


»RUN PR1301 

Which terminal do you want to use (1-7) ? 7 
** Attach Failure ** 

Which terminal do you want to use (1-7) ? 0 
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13-1. FORTRAN IV 
-EDIT/CREATE PR1301.FOR 


PROGRAM PR1301 
BYTE PROMPTC 120) ! 


BYTE MSGBFRC80) H 
BYTE ASCIZ 

INTEGER*2 IMSBC8) 7 
INTEGER*2 ITSBC4) ! 
DATA ASCIZ/‘0°/ ! 


CALL IPOKEC'44, IPEEK("44) 
IERR=MTSTATCIMSB) ! 
IF CIMSBC3) .EQ@. 0) GO TO 


OUTPUT BUFFER 
INPUT BUFFER 


MT STATUS BLOCK 

TERMINAL STATUS BLOCK 

ASCII ZERO 

-OR. 40000) ! ENABLE LC 
GET MT STATUS 

110 } EXIT IF NO MT SUPPORT 


Cc 

Cc Ask for which terminal the users. wishs to attach. 

c : 

CALL CONCATC’Which terminal do you want to use (1-7) 
1 "200,PROMPT) 

10 CALL GTLINCMSGBFR,PROMPT) 

c : 

Cc Validate input -- user must have typed one character 

c in the range 0 to 7. 

c 
IF CMSGBFRC1) .£@. 0) GO TO 10 ! REPEAT IF BLANK 
IF (MSGBFRC2) .NE. 0) GO TO 10 ! REPEAT IF TOO LONG 
IF CMSGBFRC1) .LT. ’0°) GO TO 10 ! REPEAT IF INVALID 
IF (MSGBFRC1) .GT. ’7°) GO TO 10 ! REPEAT IF INVALID 
ILUN=MSGBFRC1)-ASCIZ ' CONVERT TO BINARY LUN 
IF CILUN .EQ@. 0) GO TO 100 ! EXIT IF LUN 0 SELECTED 

c 

Cc Attach the terminal. 

c 
IERR=MTATCHCILUN, , 1JOB) - 

IF CIERR .EQ@. 0) GO TO 30 ! IF ATTACH SUCCEEDED 
CALL PRINTC’** Attach Failure **’) 
GO TO 10 | ! TRY AGAIN 

c 

c Get terminal status block for attached terminal 

Cc and enable lower case input for terminal. 

c : 

30 IERR=*MTGETCILUN, ITSB) ! GET TERMINAL STATUS 
ITSBC1)*ITSBC1) .OR. "40000 ! ENABLE LOWER CASE 
IERR=MTSETCILUN, ITSB) ! WRITE NEW STATUS 
TERR=MTRCTOCILUN) ' FORCE UPDATE OF STATUS 

C 

c Ask user to type his name. 

c 
CALL MTPRNTCILUN, “Who are you? ‘) 

c 

C And read reply terminated by <CR>. 

Cc 
DO 60 I=1,80 
TERR*MTINCILUN,MSGBFRCI)) ! GET A CHARACTER 
IF CMSGBFRCI) .EQ@. "15) GO TO 70 ! DONE IF <CR> 

60 CONTINUE 

c 

Cc If buffer overflowed, clear last byte. 
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anon 


MSGBFRC1)=0 ! REPLACE <CR> WITH NULL 
Output the message. 


CALL CONCATC ‘Welcome to Multiterminal RT-11, °%, 
MSGBFR,PROMPT) 
CALL MTPRNTCILUN,PROMPT) 


Now detach terminal and exit. 


IERR=*MTDTCHCILUND 
CALL EXIT 


Handle error if no MT support available. 
CALL PRINTC’** No Multiterminal Support **’) 


CALL EXIT 
END 


-SHOW TERMINALS 


Unit Owner Type WIDTH TAB CRLF FORM SCOPE SPEED 
0 Local DL 80 No Yes No Yes N/A 
1 Local DL 80 No Yes No No N/A 
2 S-Console DL 80 Yes Yes No Yes N/A 


~EXECUTE/LINKLIBRARY:SY:FORLIB PR1301.FOR 
Which terminal do you want to use (1-7) ? 7 
** Attach Failure ** 

Which terminal do you want to use (1-7) ? 0 


»RUN PR1301 
Which terminal do you want to use (1-7) ? 2 
Who are you? 


Ann 


Welcome to Multiterminal RT-11, Ann 
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CHAPTER 14 


14-1. MACRO-11 
-EDIT/CREATE PR1401.MAC 
-MACRO PR1401 

»LINK PR1401 

-COPY TT: TRAN1.XYZ 
Files copied: 


“TEST DATA FILE WHICH WILL BE COPIED TO TRAN2.XYZ 


#*#* EQRF ### 
“2TT: to DK: TRAN1.XYZ 


-TYPE TRAN2.XYZ 
2PIP-F-File not found DK:TRAN2.XYZ 


-RUN PR1401 “ 
Program copies TRAN1.XYZ to TRAN2.XYZ 


-TYPE TRAN2.XYZ 
TEST DATA FILE WHICH WILL BE COPIED TO TRAN2. XYZ 


ee EOF Ree 

-DEL TRAN1.XYZ 

-RUN PR1401 

Program copies TRAN1.XYZ to TRAN2.XYZ 
Error on LOOKUP of input file 


-COPY PR1401.MAC PR1801.MAC 


-EDIT PR1401.MAC 
ANNCE: .ASCIZ “Program copies PR1401.MAC to 123456.TMP"™ 


INFILE: .RADSO /DK PR1401MAC/ ;Copy from DK:PR1401.MAC 
OQUTFIL: .RADSO /DK 1234S6TMP/ ; to DK:123456.TMP 


-EXECUTE PR1401.MAC 
Program copies PR1401.MAC to 123456.TMP 


-DIFF PR1401.MAC 123456. TMP 
2SRCCOM-I-No differences found 


-EDIT PR1401.MAC 
BUFFER: .BLKW 512. ;File 1/0 Buffer 


1$; -READW #EMTARG, #3, BUFFER, #512. ,R1 


2s: -WRITW #EMTARG, #0,#BUFFER,#S12.,R1 
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BCS WERR sBranch on write failure 
ADD #2,R1 ;Update block number 
BR 1$ sAnd read next block 


-DELETE 123456.TMP 


-EXECUTE PR1401.MAC 
Program copies PR1401.MAC to 123456.TMP 


-DIFF PR1401.MAC 123456. TMP 
2SRCCOM-I-No differences found 


14-1. FORTRAN IV 
-EDIT/CREATE PR1402.FOR 
-COPY PR1402.FOR TRAN1.XYZ 
-DEL TRAN2.XYZ 


~-EXECUTE/LINKLIBRARY:SY:FORLIB PR1402.FOR 
Program copies TRAN1.XYZ to TRAN2.XYZ 


-DIFF TRAN1.XYZ TRAN2. XYZ 
?SRCCOM-I-No differences found 


-DELETE TRAN1.XYZ 
«RUN PR1402 
Program copies TRAN1.XYZ to TRAN2.XYZ 
Error on LOOKUP of input file 
-COPY PR1402.FOR PR1802.FOR 
-EDIT PR1402.FOR 
DATA INFILE/2RDK,3RPR1,3R402,3RFOR/ 
DATA OUTFIL/2RDK,3R123,3R456,3RTMP/ 
CALL PRINTC’Program copies PR1402.FOR to 123456.TMP’) 


-EXECUTE/LINKLIBRARY:SY:FORLIB PR1402.FOR 
Program copies PR1402.FOR to 123456.TMP 


-DIFF PR1402.FOR 123456. TMP 
?2?SRCCOM-I-No differences found 


-EDIT PR1402.FOR 
INTEGER*2 BUFFERCS12),BLOCK 


20 IERR = IREADWC(S512,BUFFER,BLOCK, INCHN) 
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30 


IF CIWRITWCS12,BUFFER,BLOCK,QUTCHN) .LT. 0) 
GO TO 101 

BLOCK = BLOCK+2 ! Update to block 

GO TO 20 ! Read next block 


-DELETE 123456.TMP 


-EXECUTE/LINKLIBRARY:SY:FORLIB PR1402.FOR 
Program copies PR1402.FOR to 123456. TMP 


-DIFF PR1402.FOR 123456.TMP 
?2SRCCOM-I-No differences found 


CHAPTER 15 


15-1. MACRO-11 ; 


-EDIT/CREATE PR1S05.MAC 


EMTARG: 
INFILE: 
OUTFIL: 
LIMITS: 


BUFF 1: 
BUFF2: 
QELMT: 


BIGEST: 


ERROR: 
EOF: 
ANNCE: 


FCHIMS: 
FCH2MS: 
LKPMES: 
ENTMES: 
RERRMS: 
WERRMS: 


PRTCT: 


-TITLE PR1505 


This program uses asynchronous double buffered 
computation. The program reads data from an 
input file, performs computation on that data, 
and writes the transformed data to the output 
file. 


-MCALL .EXIT -FETCH .LOOKUP .ENTER’ .PRINT 
-MCALL .READ -WRITE .CLOSE .SRESET .WAIT 
-MCALL .QSET 


- BLKW 6 ;EMT argument block 
»RADSO /DK TRAN1 XYZ/ ;Copy from DK: TRAN1.XYZ 
-RADSO /DK TRAN2 XYZ/ ; to DK: TRAN2.XYZ 
«LIMIT sHigh/low program limits 
-BLKW 256. 3File 1/0 Buffer 1 

- BLKW 256. ;File I/O Buffer 2 

- BLKW 10. ;Queue element 

- BLKW 1 ;Stores largest value 
-BYTE s;Error status byte 

- BYTE sEnd of File flag 
-ASCIZ “Program copies TRAN1.XYZ to TRAN2.XY2" 


-ASCIZ “Error on FETCH of output handler" 
-ASCIZ “Error on FETCH of input handler" 
-ASCIZ “Error on LOOKUP of input file” 

-ASCIZ “Error on creation of output file" 
-ASCIZ “Read error, copy aborted" 

-ASCIZ “Write error, copy aborted" 

-ASCIZ “Protected output file already exists" 
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» EVEN 
-SBTTL SETUP -- Setup Files For Copy 


$ This routine sets up files for I/O. 
: The file specifications are fixed. 


5 Returns with C-Bit SET on error. 


? 
SETUP: MOV R1,-(CSP) ;Save register 


«PRINT #ANNCE 3;Announce program 
$ Fetch device handlers 
MOV LIMITS+2,R1 ;Load high Limit 
-FETCH R1,#OUTFIL 3Get output handler 
BCS FCHIER ;Branch on FETCH error 
MOV RO,R1 sLoad high limit 
»-FETCH RO,#INFILE 3Get input handler 
BCS FCH2ER s;Branch on FETCH error 
: Open files 
»~LOOKUP #EMTARG,#3,#INFILE 
BCS LKPERR ;Branch if open failed 
MOV RO,R1 jLoad input file length 
-ENTER #EMTARG,#0,#OUTFIL 
BCC DONE ;Branch if successful 
; Error Routines 
-PRINT #ENTMES ;Issue create failure msg 
BR ERDONE ;And finish up 
LKPERR: .PRINT #LKPMES ;Issue open failure msg 
BR ERDONE 3And finish up 
FCH2ER: .PRINT #FCH2MS ;Issue FETCH error 
BR ERDONE ;And finish up 
FCHIER: .PRINT #FCH1MS ;Issue FETCH error 
ERDONE: SEC ;Indicate error occurred 
DONE: MOV CSP)+,R1 sRestore R1 (save C-bit) 
RETURN sReturn to caller 
-SBTTL CMPRTN -- Computation Routine 
3 Routine assumes the input file is opened on 
5 channel 3 and the output on channel 0. 
: Returns with C-BIT SET on error. 
3 Note: All registers except RO are preserved. 
CMPRTN: MOV R1,-CSP) ;Save registers 
MOV R2,-CSP) 
MOV R3,-CSP) 
MOV R4,-CSP) 
MOV RS,-CSP) 
-QSET *QELMT, #1 ;Allocate a queue element 
BEG: »READ #EMTARG, #3,*BUFF1,#2S56.,#0 
Bcc INIT - ;Branch if read ok 
TSTB e#S2  3End-of-File? 
BEQ EXIT s;Branch if so, all done 


BR RDERR s;Issue read error 
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INIT: MoV #1,R1 sLoad read block number 
CLR RS ; sLoad write block number 
MOV *#BUFF2,R2 ;R2 ==> input buffer 
MOV #BUFF1,R3 <3R3 ==> output buffer 
CLRB ERROR ;Clear error flag 
CLRB EOF 3;Clear EOF flag 

SLOOP: .WAIT #3 ;Wait for input to finish 
BCS RDERR ;Branch on error 
-READ #EMTARG, #3,R2,#256. ,R1 
BCC comp :Branch if read succeeded 
TSTB a#52 ;End-Of-File CEOF)? 
BNE RDERR ;Branch if fatal error 
INCB EOF ;Set EOF encountered flag 


; Perform computation on previously read block. 

7 This routine finds the largest value within the 
: block and subtracts each word in the block from 
: that value. 


COMP: MOV #255.,R0 sInitialize counter 


MOV R3,R4 ;Load buffer starting address 

MOV CR4)+,BIGEST ;Assume ist word is biggest 
10$; CMP CR4)+,BIGEST 3Next word bigger? 

BLT 208 ;Branch if not 

MOV -2(R4) ,BIGEST ;Otherwise, save new biggest 

20$: DEC RO ;Done? 

BNE 10$ 3;Branch if not 

MOV #256.,R0 sInitialize counter 

MOV - R3,R4 ;Load buffer starting address 
30$: MOV BIGEST,-(SP) . ;Put biggest value onto stack 

SUB CR4),CSP) ;Stack = biggest - current 

MOV C(SP)+,CR4)+ ;Save result 

DEC RO ; ;Done? 

BNE 30$ sBranch if not 


; Write out buffer on which computation has just 
; been performed. 


eWRITE #EMTARG,#0,R3,256.,R5 


BcS WERR ;Branch on write error 
TSTB EOF s;EQOF on last read? 
BGT EXIT sBranch if so 
MoV R2,R4 ;Otherwise, switch input 
MOV R3,R2 ; and output buffer 
MOV R4,R3 ; 
INC R1 ;Update input block # 
INC R5 ; ;Update output block # 
BR SLOOP sAnd continue 

J 

. Error messages and cleanup. 

? 

RDERR: .PRINT #RERRMS ;Issue read error msg 


BR EREXIT 3;And finish up 
WERR: «PRINT #WERRMS ;Issue write error msg 
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EREXIT: DECB ERROR ;Set error flag 

EXIT: MOV CSP)+,RS ;Restore saved registers 
MOV CSP)+,R4 
MOV CSP)+,R3 
MOV CSP)+,R2 
MOV CSP)+,R1 
WAIT #0 ;sWait for last output 
BCC © 1$ ;Branch if successful 
»~PRINT #WERRMS ;Issue write error msg 
BR es 

1$: TSTB ERROR ;Set C-Bit? (clear it) 
BEQ 3$ sBranch if not 

es: SEC sOtherwise, set it 

3$: RETURN sReturn to caller 
-SBTTL CLSCHN -- Cleanup For Copy Program 

CLSCHN: .CLOSE #3 ;Close input file 
-CLOSE #0 ;Close output file 
BCC RESET ;Branch on success 
-PRINT #PRTCT ;Issue protected file msg 

PRGCHN: ;Purge files 

RESET: .SRESET ;Reset Cpurge files) 
RETURN ;Return to caller 
-SBTTL MAIN PROGRAM 

START: CALL SETUP ;Open files 
BCS 1$ ;Branch on error 
CALL CMPRTN sTransfer the file 
Bcs 1$ ;Branch on error 
CALL CLSCHN sClose the files 
BR 2s 

1$; CALL PRGCHN ;Purge the files 

2$: EXIT 


BAS 


» END START 


BASIC-11/RT-11 V02-03 
OPTIONAL FUNCTIONS CALL, NONE, OR INDIVIDUAL)? A 


READY 


NEW 
100 
110 
120 
130 
140 
150 
160 
RUN 


BUILD 

OPEN “DK: TRAN1.XYZ" FOR OUTPUT AS FILE #1% 
DIM #1%,A%C€S11%) 

FOR Y%=0% TO 511% 

AXCYRI=Y% 

NEXT Y% 

CLOSE 

END 


BUILD 20-MAR-84 10:59:10 


READY 


BYE 
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-DUMP/TERMINAL TRAN1.XYZ/NOASCII 

DK: TRAN1.XYZ 

BLOCK NUMBER 000000 

000/ 000000 000001 000002 000003 000004 
020/ 000010 000011 000012 000013 000014 
040/ 000020 000021 000022 000023 000024 
060/ 000030 000031 000032 000033 000034 
100/ 000040 000041 000042 000043 000044 
120/ 000050 000051 000052 000053 000054 
140/ 000060 000061 000062 000063 000064 


620/ 000710 000711 000712 000713 000714 
640/ 000720 000721 000722 000723 000724 
660/ 000730 000731 000732 000733 000734 
700/ 000740 000741 000742 000743 000744 
720/ 000750 000751 000752 000753 000754 
740/.000760 000761 000762 000763 000764 
760/ 000770 000771 000772 000773 000774 


-EXECUTE PR1S05.MAC 
Program copies TRAN1.XYZ to TRAN2.XYZ 


-DUMP/TERMINAL TRAN2.XYZ/NOASCII 

DK: TRAN2. XYZ 

BLOCK NUMBER 000000 

000/ 000377 000376 000375 000374 000373 
020/ 000367 000366 000365 000364 000363 
040/ 000357 000356 000355 000354 000353 
060/ 000347 000346 000345 000344 000343 
100/ 000337 000336 000335 000334 000333 
120/ 000327 000326 000325 000324 000323 
140/ 000317 000316 000315 000314 000313 


620/ 000067 000066 000065 000064 000063 
640/ 000057 000056 000055 000054 000053 
660/ 000047 000046 000045 000044 000043 
700/ 000037 000036 000035 000034 000033 
720/ 000027 000026 000025 000024 000023 
740/ 000017 000016 000015 000014 000013 
760/ 000007 000006 000005 000004 000003 


000005 
000015 
000025 
000035 
000045 
000055 
000065 


000715 
000725 
000735 
000745 
000755 
000765 
000775 


000372 
000362 
000352 
000342 
000332 
000322 
000312 


000062 
000052 
000042 
000032 
000022 
000012 
000002 


000006 
000016 
000026 
000036 
000046 
000056 
000066 


000716 
000726 
000736 
000746 
000756 
000766 
000776 


000371 
000361 
000351 
000341 
000331 
000321 
000311 


000061 
000051 
000041 
000031 
000021 
000011 
000001 


000007 
000017 
000027 
000037 
000047 
000057 
000067 


000717 
000727 
000737 
000747 
000757 
000767 
000777 


000370 
000360 
000350 
000340 
000330 
000320 
000310 


000060 
000050 
000040 
000030 
000020 
000010 
000000 
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15-1. FORTRAN IV 
-EDIT/CREATE PR1506.FOR 


PROGRAM PR1S06 
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Cc 
C This program reads data from the input file, 
C performs computation on the data read, and 
Cc writes the transformed data to the output file. 
Lv This program uses asynchronous I/0 to allow the 
Cc computation to occur during I/0 operations. 
Cc 
LOGICAL*1 SETUP ,CMPRTN 
LOGICAL*1 ERROR 
Cc 
ERROR = SETUPC) ! Open files 
IF CERROR) GO TO 20 ! Stop on setup error 
ERROR = CMPRTNC) ! Copy file 
IF CERROR) GO TO 20 ! Stop on error 
CALL CLSCHN ! Close channels 
GO TO 30 ! Exit 
20 CALL PRGCHN ! Purge channels 
30 CALL EXIT 
END 
FUNCTION SETUP 
Cc 
c This routine sets up the files for I/O. 
Cc The file specifications are fixed in the version. 
Cc 
Cc Function returns .TRUE. if an error occurred. 
Cc 
LOGICAL*1 SETUP 
INTEGER*2 INCHN,QUTCHN 
COMMON /CHNNLS/ INCHN,OUTCHN 
Cc 
Cc Channel numbers in common because they are used 
Cc by CMPRTN, CLSCHN, and PRGCHN. 
Cc 
INTEGER*2 INFILEC4),OUTFILC4) 
DATA INFILE/2RDK,3RTRA,2RN1,3RXYZ/ ! Input & output 
DATA OUTFIL/2RDK,3RTRA,2RN2,3RXYZ/ ! file specs 
Cc 
Cc Output introductory message and allocate channels. 
Cc 
CALL PRINTC’Program copies TRAN1.XYZ to TRAN2.XYZ’) 
INCHN = IGETCC) 
QUTCHN = IGETCC) 
Cc 
C Fetch needed device handlers. 
Cc 
IF CIFETCHCOUTFILC1)) .NE. 09 GO TO 101 
IF CIFETCHCINFILEC1)) .NE. 0) GO TO 102 
Cc 
Cc Open input file. 
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° 


104 
200 


2or0Qa 0c oO 


2000 


LENGTH = LOOKUPCINCHN, INFILE) 
IF CLENGTH .LT. 0) GO TO 103 


Create output file. 


IF CIENTERCOUTCHN, OUTFIL, LENGTH) -LT. 0) GO TO 104 


“SETUP = .FALSE. §' Return success 


RETURN 
ERROR ROUTINES 


CALL PRINTC’Error on FETCH of output handler’) 
GO TO 200 

CALL PRINTC’Error on FETCH of input handler’) 
GO TO 200 

CALL PRINTC’Error on LOOKUP of input file’) 

GO TO 200 

CALL PRINTC’Error on creation of output file’) 
SETUP = .TRUE. ! Return error 

RETURN 

END 

FUNCTION CMPRTN 


Double-buffered computation routine. 


Function-returns .TRUE. on error. 
NOTE: Some severe errors will abort the program. 


LOGICAL*1 CMPRTN 

INTEGER*2 INCHN,OUTCHN 

COMMON /CHNNLS/ INCHN,OUTCHN 

INTEGER*2 BUFFERC256,2),BLO0CK, INPTR,OUTPTR 

LOGICAL*1 FRSTTM ! Once only flag 

DATA FRSTTM/.TRUE./ 

IF C.NOT. FRSTTM) GO TO 10 ! Do QSET only once 

IF CIQSETC1) .NE. 0) STOP ‘No room for queue:element’ 
FRSTTM = .FALSE. 


‘Begin by reading into buffer 1. 


IERR = IREADC256, BUFFERC1,1),0, INCHN) 

IF CIERR .GE. 0) GO TO 20 ! Successful read 

IF CIERR .EQ@. (€-1))-G60 TO 150 ! EQF means all done 
GO TO 100 §! Read error 


‘Initialize block numbers and flags. 


BLOCK = 1 ! Initialize block number & 
INPTR = 2 ! input buffer number & 
OUTPTR = ‘1 ! output buffer number 


Loop: Wait for input to complete, compute, 
output. 
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0 IF CIWAITCINCHN) .NE...03 GO TO 100 § Error on read 
Read next block into input buffer. 


IERR = IJREADC2S6,BUFFERC1,INPTR),BLOCK, INCHN)D 
IF CIERR .LT. €-1)) GO TO 100!-Error on read 


Cc 
Cc Perform computation on output buffer while read is 
Cc in progress. Computation consists of subtracting 
c each word in the block from the largest value in 
Cc that block. 
Cc 
50 IBIG = BUFFERC1,OUTPTR) 
DO 60 1#2,256 
IF CBUFFERCI,OUTPTR) .GT. IBIG) 
1 IBIG=BUFFERCI,OUTPTR)D 
60 CONTINUE 
DO 70 1I=1,256 
BUFFERCI,OUTPTR) = IBIG-BUFFERCI,OUTPTR)- 
70 CONTINUE 
Cc 
C Write out buffer on. which computations have just 
Cc completed. 
C. 
IF CIWRITEC256,BUFFERC1,OUTPTR),BLOCK=1;OUTCHN) .LT. 0) 
1 GO TO. 101 ! Error on write 
Cc 
Cc Check if last read resulted in EOF. 
Cc 
IF CIERR .EQ@. €-1)) GO TO 150 ! Copy completed. 
C.. 
Cc Otherwise, switch buffers and advance block. number. 
Cc 
ITMP = INPTR 
INPTR = OUTPTR 
OUTPTR = ITMP 
BLOCK = BLOCK+1 
Go TO 30 ! Repeat 
Cc 
Cc ERROR ROUTINES 
Cc 
100 CALL PRINTC’Read error, copy aborted’) 
GO TO 149 
101 CALL .PRINTC’Write error, copy aborted’) 
140 CMPRTN = .TRUE. 
RETURN 
Cc ‘ 
c Wait for last output to complete and return. 
Cc 
150 IF CIWAITCOUTCHND .NE. 0) GO TO 101 
CMPRTN = .FALSE. 
RETURN 


END 
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SUBROUTINE CLSCHN 


oO 


Close files. 


INTEGER*2 INCHN,OUTCHN 
COMMON /CHNNLS/ INCHN,OUTCHN 
CALL CLOSECCINCHN) 
IF CICLOSECOUTCHN) .EQ. 4) CALL PRINT 
1 C’Protected output file already exists’) 
RETURN 
END 
SUBROUTINE PRGCHN 


oO 


Purge channels. 


INTEGER*2 INCHN,OUTCHN 
COMMON /CHNNLS/ INCHN,OUTCHN 
CALL PURGECINCHND 

CALL PURGECOUTCHN) 

RETURN 

END 


- BAS 
BASIC-11/RT-11 V02-03 
OPTIONAL FUNCTIONS CALL, NONE, OR INDIVIDUAL)? A 


READY 


NEW BUILD 


100 OPEN "DK: TRAN1.XYZ" FOR OUTPUT AS FILE #1% 
110 DIM #1%,A%€511%) 

120 FOR Y%=0% TO 511% 

130 AXCYZ)=Y% 

140 NEXT Y% 

150 CLOSE 

160 END 

RUN 


BUILD 20-MAR-84 11:34:15 


READY 
BYE 


-» DUMP/ TERMINAL TRAN1.XYZ/NOASCII 
DK: TRAN1.XYZ 
BLOCK NUMBER 000000 


. 0007 000000 000001 000002 000003 000004 000005 000006 


020/ 000010 000011 000012 000013 000014 000015 000016 
040/ 000020 000021 000022 000023 000024 000025 000026 
060/ 000030 000031 000032 000033 000034 000035 000036 
100/ 000040 000041 000042 000043 000044 000045 000046 
120/ 0000S0 000051 000052 000053 000054 000055 000056 
140/ 000060 000061 000062 000063 000064 000065 000066 


000007 
000017 
000027 
000037 
000047 
000057 
000067 
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620/ 000710 000711 000712 000713 000714 
640/ 000720 000721 000722 000723 000724 
660/ 000730 000731 000732 000733 000734 
700/ 000740 000741 000742 000743 000744 
720/ 000750 000751 000752 000753 000754 
740/ 000760 000761 000762 000763 000764 
760/ 000770 000771 000772 000773 000774 


-EXECUTE PR1SO0G/LINKLIBRARY:SY:FORLIB 
Program copies TRAN1.XYZ to TRAN2.XYZ2 


-DUMP/TERMINAL TRAN2.XYZ/NOASCII 

DK: TRAN2. XYZ 

BLOCK NUMBER 000000 

000/ 000377 000376 000375 000374 000373 
020/ 000367 000366 000365 000364 000363 
040/ 000357 000356 000355 000354 000353 
060/ 000347 000346 000345 000344 000343 
100/ 000337 000336 000335 000334 000333 
120/ 000327 000326 000325 000324 000323 
140/ 000317 000316 00031S 000314 000313 


620/ 000067 000066 000065 000064 000063 
640/ 000057 000056 000055 000054 000053 
660/ 000047 000046 000045 000044 000043 
700/ 000037 000036 000035 000034 000033 
720/ 000027 000026 000025 000024 000023 
740/ 000017 000016 000015 000014 000013 
760/ 000007 000006 000005 000004 000003 


15-2. 


(1) Event-driven 
(2) Asynchronous 
(3) Synchronous 


000715 
00072S 
000735 
000745 
000755 
000765 
000775 


000372 
000362 
000352 
000342 
000332 
000322 
000312 


000062 
000052 
000042 
000032 
000022 
000012 
000002 


000716 
000726 
000736 
000746 
000756 
000766 
000776 


000371 


000361 
000351 
000341 
000331 
000321 
000311 


000061 
000051 
000041 
000031 
000021 
000011 
000001 
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000717 
000727 
000737 
000747 
000757 
000767 
000777 


000370 
000360 
000350 
000340 
000330 
000320 
000310 


000060 
000050 
000040 
000030 
000020 
000010 
000000 
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CHAPTER 17 


17-1. (Step 1) MACRO-11 
-EDIT/CREATE PR1701.MAC 


«TITLE PR1701 Solution 17-1 Background 
-MCALL .QSET -SDATW .RCVDW .PRINT .EXIT 


«-NLIST BEX 

-ENABL LC 
AREA: - BLKW 5 ;EMT argument block 
QLIST: .BLKW 2*7 ;Queue element list 
INBUF: .BLKW 42. ;Input buffer 


‘SNDBF: .BLKW 42. 


SNDERR: .ASCIZ2 "?PR1701 Send error, no other job" 
RCVER1: .ASCIZ "™?PR1701 Receive error, no other job” 


-EVEN 
START: .QSET #QLIST,#2 sAllocate queue elements 
MOV *RCVER1,R2 ;Assume no other job 
»RCVDW #AREA,*#INBUF,#41. ;Wait for message 
BCS ERR ;Report failure 
MOV *INBUF+2,R2 sPoint to received data 
MOV #SNDBF ,R3 sPoint to send buffer 
10$; TSTB CR2)+ ;Search for null byte 
BNE 10 ;Loop until byte found 
“DEC R2 ;Backup over null byte 
20$: MOVB -CR2), CR3BD+ ;Move string to output 
CMP R2,#INBUF +2 sAl1 done? 
_BHI 20 sLoop until done if not 
CLRB CR3) sInsert null byte 
MOV INBUF ,R1 sLoad word count 
MOV #SNDERR,R2 sAssume send error 
«SDATW #AREA,#SNDBF,R1 ;Send message and wait 
BCS ERR ;Report failure 
EXIT ;Otherwise, exit 
ERR: -PRINT R2 ;Print error message 
EXIT sAnd exit 


«END START 


~-EDIT/CREATE PR1702.MAC 


-TITLE PR1702 Solution 17-1 Foreground 
-MCALL .PEEK «POKE -QSET -GTLIN 
-MCALL .SDATW .RCVDW .PRINT .EXIT 


-ENABL LC 
AREA: - BLKW S ;EMT argument block 
QLIST: .BLKW 2*7 sQueue element list 
INBUF: .BLKW 42. ;Input buffer 


PROMPT: .ASCIZ “Input your message: " 

REPLY: .ASCIZ “In reverse, that becomes:" 

SNDERR: .ASCIZ “?PR1702 Send error, no other job™ 
RCVER1: .ASCIZ "?PR1702 Receive error, no other job" 
RCVER2: .ASCIZ "?PR1702 Receive error, length error™ 
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EVEN 
JSW 
LOWER 
START: .QSET 
«PEEK 
MOV 
BIS 
-POKE 
-GTLIN 
Mav 
10$:; TSTB 
BNE 
SUB 
INC 
ASR 
MOV 
- SDATW 
BCS 
MoV 
»RCVDW 
BCS 
MOV 
CMP 
BNE 
»PRINT 
«PRINT 
«EXIT 
ERR: «PRINT 
EXIT 
-END 


. 44 
- 40000 
#QLIST,#2 
#AREA, #USW 
RO,R1 

#LOWER,R1 
#AREA, #USW,R1 
#INBUF , #PROMPT 
#INBUF ,R1 

CR1)+ 

10$ 

#INBUF,R14 

R1 

R1 

#SNDERR,R2 
#AREA, #INBUF,R1 
ERR 

#RCVER1,R2 
#AREA, #INBUF,R1 
ERR 

#RCVER2,R2 

R1, INBUF 

ERR 

#REPLY 

#INBUF +2 


R2 


START 


-MACRO PR1701,PR1702 


-LINK PR1701 


»LINK/FOREGROUND PR1702 


«RUN PR1701 


sAllocate queue elements 
;Get JSW 

;Save the value 

;Enable lower case input 
;Set JSW 

;Get input from console 
;Load string buffer addr 
;Search for null byte 
;Loop until byte found 
;Calculate string length 
;Round up to next word 
sCalculate word count 
;Assume no other job 
3;Send message to backgrd 
;Report error 

;Assume receive error 
sWait for reply 

;Report error 

;Assume invalid length 
;Check received length 
;Report error 

;Print heading 

;Print reply 

sExit 

;Print error message 
sAnd exit 


?PR1701 Receive error, no other job 


-FRUN PR1702 


F> 


Input your message: 


B> 


»RUN PR1701 


F> 


This is the message for the foreground job. 
In reverse, that becomes: 
-boj dnuorgerof eht rof egassem eht si sihT 


B> 
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17-1. (Step 1) FORTRAN IV 


qoaaoaonaan 


oO 


OQ 


Qqanaoaaoaaan 


a 


a 


PROGRAM PR1701 
Solution to 17-1 Background Job 


Receive string from foreground, reverse it, 
and return it. 


BYTE STR1(84), STR2(84), STRINGC82) 
INTEGER*2 ICOUNT 
EQUIVALENCE CICOUNT,STR1),CSTRING,STR1(3)) 


Allocate queue elements. 


IF CIQSETC2) .NE: 0) 
STOP °?PR1701 Insufficient queue elements’ 


Receive string from foreground job. 


IF CIRCVDWCSTR1,41) .NE. 0) 
STOP ’?PR1701 Receive error’ 


L=LENCSTRING) ! Load string length 
DO 10 I=#1,L 

STR2CI)=STRINGCL-I+1) ! Reverse string 
STR2¢CL+1)=0 ! Append null byte 
IL=I COUNT § Save word count 


Send reversed string to foreground job. 


IF CISDATWCSTR2,IL) .NE. 0) 
STOP ’?PR1701 Send error’ 

CALL EXIT 

END 


PROGRAM PR1702 
Solution to 17-1 Foreground Job 


Read string, send it to background job, receive 
string from background job, and print iti. 


BYTE STR1(84), STR2C€84), PROMPTC80) 
INTEGER*2 ICOUNT 
EQUIVALENCE CICOUNT,STR2) 


Allocate queue elements. 


IF CIQSETC2) .NE. 0) 
STOP ’?PR1702 Insufficient queue elements’ 


Prompt for string and get it. 


CALL IPOKEC"44,"40000 .OR. IPEEKC™44)) 
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Q 


CALL SCOPYC’ Input your message: ’,PROMPT) 
CALL GTLINCSTR1,PROMPT) 
L=CLENCSTR1)+2)/2 ! Length in words 


Send string to background job. 


IF CISDATWCSTR1,L) .NE. 0) 
STOP ’?PR1702 Send error’ 


Receive reversed string and print it. 


IF CIRCVDWCSTR2,L) .NE. 0) 

STOP ’?PR1702 Receive error’ 
IF CICOUNT .NE. L) 

STOP ’?PR1702 Receive length error’ 
CALL PRINTC’In reverse, that becomes:’) 
CALL PRINTCSTR2C3)) 

CALL EXIT 
END 


17-1. (Step 2) FORTRAN IV 


-EDIT/CREATE PR1703.FOR 


Qoaaoaoangaaan 


ie) 


iv] 


i?) 


PROGRAM PR1703 
Solution to 17-1 (Step 2) Background Job 


Receive shared buffer from foreground, 
reverse string, and return it. 


EXTERNAL REV 
BYTE STR2(84) 
INTEGER*2 MSGC3) 


Allocate queue elements. 


IF CIQSETC2) .NE. 0) 
STOP ’?PR1703 Insufficient queue elements’ 


Receive string from foreground job. 


IF CIRCVDWCMSG,2) .NE. 0) 
STOP ’?PR1703 Receive error’ 
CALL INDIRCREV,1,MSGC2),0,STR2) ! Reverse string 


Send reversed string. 


IF CISDATWCMSGC2),1) .NE. 0) 
STOP ’?PR1703 Send error’ 

CALL EXIT 

END 
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SUBROUTINE REV CISTR,OSTR) 


Cc 
Cc Subroutine to reverse string. 
C 
BYTE ISTRC84),0STRC84) 
INTEGER*2 L 
L=LENCISTR) ! Get length of string 
DO 10 1#1,L 
10 OSTRCID=ISTRCL-I+1) ! Reverse string 
DO 20 I#1,L 
20 ISTRCI)=OSTRCI)D § Move back to buffer 
RETURN 
END 


-EDIT/CREATE PR1704.FOR 


PROGRAM PR1704 


Cc 
Cc Solution to 17-1 (Step 2) Foreground Job 
Cc 
Cc Read string and share buffer with background, 
Cc wait for returned string, and print results. 
Cc 
BYTE STR1(€84), PROMPTC80) 
INTEGER*2 ICOUNT,MSGC2) 
EQUIVALENCE CICOUNT,STR1) 
Cc 
Cc Allocate queue elements... 
Cc 
IF CIQSETC2) .NE. 0) 
1 STOP ’?PR1704 Insufficient queue elements’ 
Cc 
C Prompt for string and get it. 
Cc 
CALL. IPOKEC"44,"40000 .OR. IPEEKC"44)) 
CALL SCOPYC’ Input your message: ’,PROMPT) 
CALL GTLINCSTR1,PROMPT) 
L=LENCSTR1) ! Get string length 
MSGC1)=IADDRCSTR1) ! Build shared 
MSGC2)=IADDRCSTR1ICL)) ! buffer descriptor 
Cc 
Cc Send data with shared buffer descriptor to 
c the background job. 
Cc 
IF CISDATWCMSG,2) .NE. 0) 
1 STOP ’?PR1704 Send error’ 
Cc 
Cc Receive reversal completed from background. 
Cc 


IF CIRCVDWCMSG,1) .NE. 0) 
1 STOP ‘’?PR1704 Receive error’ 
IF CMSGC1) .NE. 1) 
1 STOP ’?PR1704 Receive length error’ 
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CALL PRINTC’In reverse, that becomes:’) 
CALL PRINTCSTR1) 
CALL EXIT 
END 
-EDIT/CREATE INDIR.MAC 
-FORTRAN PR1703,PR1704 
-MACRO INDIR 
-LINK PR1703,INDIR,SY:FORLIB 
»LINK/FOREGROUND PR1704,SY:FORLIB 


-FRUN PR1704 


F> 
?Err 62 FORTRAN start fail 


B> 


-FRUN PR1704/BUFFER: 2000 


F> 
Input your message: 


B> 


«RUN PR1703 


F> 

This is the message for PR1703. 
In reverse, that becomes: 
-3071RP rof egassem eht si sihT 


B> 
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17-1. (Step 2) MACRO-11 


AREA: 

QLIST: 
MSG: 

TMPEF : 
SNDERR: 
RCVER1: 
RCVER2: 


START: 


20$: 


30$: 


ERR: 


AREA: 

QLIST: 
INBUF : 
MSG: 

PROMPT: 
REPLY: 
SNDERR: 
RCVER1: 


-TITLE 
-MCALL 
eNLIST 
» ENABL 
- BLKW 
- BLKW 
- BLKW 
- BLKW 
-ASCIZ 
-ASCIZ 
-ASCIZ 
- EVEN 
-QSET 
MOV 
-RCVDW 
BCS 
MoV 
CMP 
BNE 
MOV 
MOV 
MOVB 
CMP 
BHI 
CLRB 
MOV 
MOVB 
BNE 
MOV 

- SDATW 
BCS 
EXIT 
»PRINT 
EXIT 
«END 


» TITLE 
«MCALL 
-MCALL 
» ENABL 
- BLKW 
- BLKW 
- BLKW 
- BLKW 
-ASCIZ 
-ASCIZ 
-ASCIZ 
-ASCIZ 
- EVEN 
JSW 
LOWER 


PR1703 Solution 17-1 (Step 2) Background 


-QSET - SDATW 
BEX 

LC 

5 

2*7 

3 

42. 


-RCVDW .PRINT .EXIT 


;EMT argument block 
s;Queue element list 
sShared buffer data 
sWork area 


"2PR1703 Send error, no other job" 
"2PR1703 Receive error, no other job™ 
"2PR1703 Receive error, data length” 


*QLIST,#2 
#*RCVER1,R2 


AREA, #MSG, #41. 


ERR 
#RCVER2,R2 
MSG, #2 

ERR 
MSG+4,R2 
#TMPBF ,R3 
-CR2),CR3)+ 
R2,MSG+2 
20$ 

CR3) 

#TMPBF ,R3 
CR3)+,CR2)+ 
30$ 
#SNDERR,R2 
#AREA, #MSG, #1 
ERR 


Re 


START 


;Allocate queue elements 
;Assume no other job 
sWait for data 

;Report failure 

;Assume length error 
s;Two words received? 
;Branch if not 

sLoad shared buffer addr 
;Load temp buffer addr 
;Move data into temp 
3All1 done? 

;Branch if not 

;Insert null byte 

;Load temp buffer addr 
;Move data into shared 
;Loop until end of text 
sAssume send error 
3;Send data and wait 
;Report failure 
sOtherwise, exit 

;Print error message 
sAnd exit 


PR1704 Solution 17-1 (Step 2) Foreground 


-PEEK -POKE 
-SDATW .RCVDW 
LC 

5 

2*7 

42. 

2 


“Input your message: 


-QSET -GTLIN 
~PRINT .EXIT 


;EMT argument block 
sQueue element list 
;Input buffer 
3;Send buffer 


“In reverse, that becomes:" 
"2PR1704 Send error, no other job" 
"2PR1704 Receive error, no other job” 


= 40000 
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START: .QSET *QLIST,#2 
»PEEK #AREA, #JSW 
MOV RO,R1 
BIS #LOWER,R1 
-POKE #AREA,#JSW,R1 
-GTLIN #INBUF ,#PROMPT 
MOV #INBUF ,R1 
10$: TSTB CR1)+ 
BNE 10$ 
DEC R1 
MOV #TNBUF ,MSG 
MOV R1,MSG+2 
MOV #SNDERR,R2 
-SDATW #AREA, #MSG, #2 
BCS ERR 
MOV #RCVER1,R2 
«RCVDW #AREA, #MSG, #1 
BCS ERR 
-PRINT #REPLY 
«PRINT #INBUF 
~EXIT 
ERR: «PRINT R2 
-EXIT 
-END START 


17-1. (Step 3) MACRO-11 


-EDIT/CREATE PR1705.MAC 


-TITLE PR1705 
-MCALL .QSET - SDATW 
-MCALL .CHCOPY .READW 
-NLIST BEX 
-ENABL LC 
AREA: - BLKW 5 
QLIST: .BLKW 2*7 
MSG: - BLKW 3 
TMPBF: .BLKW 92. 
INBUF: .BLKW 42. 
SNDERR: .ASCIZ "?PR1705 
RCVER1: .ASCIZ "?PR1705 
RCVER2: .ASCIZ "“?PR1705 
CHERR: .ASCIZ “?PR1705 
RDERR: .ASCIZ "?PR1705 
WRTERR: .ASCIZ2 "?PR1705 
CLSERR: .ASCIZ "?PR1705S 
- EVEN 
START: .QSET *QLIST,#2 
MOV #RCVER1,R2 
»-RCVDW #AREA, #MSG, #2 


;Allocate queue elements 
sGet JSW 

;Save the value 

sEnable lower case input 
;Set JSW 

;Get input from console 
sLoad string buffer addr 
;Search for null byte 
;Loop until byte found 
;Backup over null byte 
;Load buffer starting 

; and ending address 
sAssume send error 

;Send data to background 
;Report error 

;Assume receive error 
;Wait for reply 

;Report error 

;Print heading 

;Print reply 

sExit 

;Print error message 
sAnd exit 


Solution 17-1 Background 


-PRINT 
.CLOSE 


.RCVDW ~EXIT 


-WRITW 


;EMT argument block 
;Queue element list 
;Shared buffer data 
sWork area 

;File input area 


Send error, no other job" 
Receive error, no other job” 
Receive error, data length" 
Channel copy error" 

Read error" 

Write error" 

Close error" 


;Allocate queue elements 
;Assume no other job 
;Receive data from frgrnd 
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;Report failure 

;Assume data length error 
3;Two words received? 
;Branch if not 

;Assume chan copy error 
j;Load foregound channel 

; number and copy it 
;Report error 

;Assume read error 


-READW #AREA,#1,#INBUF ,MSG+4,#0 ;Read data 


;Report error 

sLoad data buffer addr 
sSearch for end of 

; buffer 

;Backup over null byte 
;Point to temp buffer 
;Move data into output 
; buffer 

;Branch if not done 
;Insert null byte 
sAssume write error 


~WRITW #AREA,#1,#TMPBF ,MSG+4,#1 sWrite data 


BCS ERR 
MOV #RCOVER2,R2 
CMP MSG, #2 
BNE ERR 
MOV #CHERR,R2 
MOV MSG+2,R3 
-CHCOPY #AREA,#1,R3 
BCS ERR 
MOV #RDERR,R2 
BCS ERR 
MOV #INBUF ,R2 
108: TSTB CR2)+ 
BNE 10$ 
DEC R2 
MoV #TMPBF ,.R3 
20$: MOVB ~CR2),CR3)+ 
CMP R2,#INBUF 
BHI 20$ 
CLRB CR3) 
MOV #WRTERR,R2 
BCS ERR 
MOV #SNDERR,R2 
.SDATW #AREA,#MSG+4, #1 
BCs ERR 
MOV #CLSERR,R2 
.CLOSE #1 
BCS ERR 
»EXIT 
ERR: -PRINT R2 
JEXIT 


«END START 


-EDIT/CREATE PR1706.MAC 


;Report error 
;Assume send error 
;Send data and wait 
;Report failure 
sAssume close error 
sClose file 

;Report error 
;Otherwise, exit 
;Print error message 
3And exit 


-TITLE PR1706 Solution 17-1 Foreground 


.MCALL «PEEK  .POKE 
.MCALL .SDATW .RCVDW 
.MCALL .ENTER .WRITH 
-ENABL LC 

AREA: .BLKW 5 

QLIST: .BLKW 2*7 

INBUF: .BLKW 42, 

MSG: .BLKW 2 

ZERO: .WORD 0 

FILE: .RADSO /DK PR1706TXT/ 


-QSET ~GTLIN 
~PRINT EXIT 
»~READW .CLOSE 


;EMT argument block 
sQueue element list 
;Input buffer 

;Send data buffer 


PROMPT: .ASCIZ “Input your message: ™ 
REPLY: .ASCII "In reverse, that becomes:"<15>¢12) 


MSGBUF: .BLKB 82. 


"2PR1706 Receive error, no other job" 


SNDERR: .ASCIZ “?PR1706 Send error, no other job™ 
RCVER1: .ASCIZ 
OPNERR: .ASCIZ “?PR1706 Enter error" 
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WRTERR: .ASCIZ “?PR1706 Write error" 
RDERR: .ASCIZ "?PR1706 Read error" 
CLSERR: .ASCIZ "“?PR1706 Close error" 
-EVEN 
JSW = 44 
LOWER = 40000 
START: -QSET #QLIST,#2 sAllocate queue elements 
»-PEEK #AREA, #JSW 3;Get JSW 
MOV RO,R1 ;Copy job status word 
BIS #LOWER,R1 ;Enable lower case input 
»~POKE #AREA, #JSW,R1 ;Set JSW 
-GTLIN #INBUF,#PROMPT ;Get input from console 
MOV #INBUF,R1 ;Load input buffer addr 
10$: TSTB CR13+ ;Search for null byte 
BNE 10$ sLoop until byte found 
SUB #INBUF,R1 ;Calculate string length 
ASR R1 ; and then word count 
MOV R1,MSG+2 sLoad word count 
MOV #OPNERR,R2 ;Assume open error 
-ENTER #AREA,#0,#FILE,#2 ;Create 2 block file 
BCS ERR ;Report error 
MOV #WRTERR,R2 sAssume write error 
-WRITW #AREA,#0,#INBUF,R1,#0 ;Write text 
BCS ERR ;Report error 
-WRITW #AREA,#0,#ZERO,#1,41 ;Zero block 1 
CLR MSG sLoad channel number 
MOV #SNDERR,R2 s;Assume send error 
~-SDATW #AREA, #MSG, #2 ;Send data 
BCS ERR ;Report error 
MOV #RCVER1,R2 ;Assume no other job 
»~RCVDW #AREA,#MSG, #1 ;Wait for reply 
BCS ERR ;Report error 
MoV #RDERR,R2 ;Assume read error 
-READW #AREA,#0,#INBUF,R1,41 ;Read data 
BCS ERR ;Report error 
MOV *CLSERR,R2 sAssume close error 
-CLOSE #0 ;Close the new file 
BCS ERR ;Report error 
MOV *INBUF ,R1 ;Prepare to move text 
MOV #MSGBUF ,R2 ; to output buffer 
20$: MOVB CR1)+,CR2)+ sMove text 
BNE 20$ sLoop until done 
«PRINT #REPLY ;Print modifed message 
~-EXIT 
ERR: «PRINT R2 ;Print error message 
~EXIT sAnd exit 
- END START 
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-MACRO PR1705,PR1706 
-LINK PR1705 


»-RUN PR1705 
2PR170S Receive error, no other job 


-LINK/FOREGROUND PR1706 
-FRUN PR1706 


F> 
Input your message: 


B> 
-RUN PR1705 


Fo 
ABCDEFGHI JKLMNOPQRSTUVWXYZ... 1234567890! 


B> 


F> 
In reverse, that becomes: 
10987654321...ZYXWVUTSRQPONMLKJIHGFEDCBA 


B> 


~ TYPE PR1706.TXT 
ABCDEFGHI JKLMNOPQRSTUVWXYZ...1234567890! 
10987654321...Z2YXWVUTSRQPONMLKJIHGFEDCBA 


17-1. (Step 3) FORTRAN IV 


PROGRAM PR1705 


C 
C Solution to 17-1 (Step 3) Background 
C 
C Receive shared file from foreground, read block 
Cc 0, reverse string, and write it to block 1. 
C 
BYTE STR1¢€84), STR2C(84) 
INTEGER*2 MSGC3) 
C 
C Allocate queue elements. 
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IF CIQSETC2) .NE. 0) 
STOP ’?PR1705 Insufficient queue elements’ 


Receive string from foreground job. 


IF CIRCVDWCMSG,2) .NE. 0) 
STOP ’?PR1705 Receive error’ 
IF CMSGC1) .NE. 2) 

STOP ’?PR170S Receive length error’ 
IF CICHCPYC1,MSGC2)) .NE. 0) 

STOP ’?PR170S Channel copy error’ 
IERR=IREADWCMSGC3),STR1,0,1) ! Read block 0 
IF CIERR .LT. 0) STOP ’?PR170S Read error’ 
L=LENCSTR1) 

DO 10 I#1,L a 

STR2CI)=STRICL-1I+1) ! Reverse string 
STR2CL+1)=0 ! Append null byte 
ITERR#=IWRITWCMSGC3),STR2,1,1) ! Write block 1 
IF CIERR .EQ. -1) 

STOP ’?PR170S Write error -- PAST EOF’ 
IF CIERR .EQ@. -2) 


STOP ’?PR170S Write error -- HARDWARE ERROR’ 


IF CIERR .EQ. -3) 
STOP ’?PR170S Write error -- FILE NOT OPEN’ 


Send reversal completed to foreground. 


IF CISDATWCMSGC(3),1) .NE. 0) 
STOP ’?PR170S Send error’ 
IF CICLOSEC1) .NE. 0) 
STOP ’?PR170S Close error’ 
CALL EXIT 
END 


PROGRAM PR1706 

Solution to 17-1 (Step 3) Foreground 

Read string and write it to a file, send 
channel to background, wait for return, and 
print results. 

BYTE STR1C€84), PROMPTC80) 

INTEGER*2 FILEC4) ,MSGC2) 

DATA FILE /3RDK ,3RPR1,3R807,3RTXT/ 


Allocate queue elements. 


IF CIQSETC2) .NE. 0) 
STOP “?PR1706 Insufficient queue elements’ 


Prompt for string and get it. 
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CALL IPOKEC"44,"40000 .OR. IPEEKC"44)) 
CALL SCOPYC’Input your message: ’,PROMPT) 
CALL GTLINCSTR1,PROMPT) 


IERR=IENTERCO,FILE,2) §' Create 2-Block file 
IF CIERR .LT. 0) 

1 STOP ’?PR1706G File create error’ 
MSGC1)=0 ! Send channel number 


MSGC2)=C(LENCSTR1)+2)/2 ! Send length in words 
IERR=IWRITWCMSGC2),5TR1,0,0) ! Write data 

IF CIERR .LT. 0) STOP “?PR1706 Write error’ 
IERR=IWRITWC1,MSG,1,0) ! Zero block 1 

IF CIERR .LT. 0) STOP “°?PR1706 Write error’ 


Cc 
C Send shared file data. 
Cc 
IF CISDATWCMSG,2) .NE. 0) 
1 STOP ’?PR1706 Send error’ 
Cc 
Cc Receive data from background. 
Cc 
IF CIRCVDWCMSG,1) .NE. 0) 
1 STOP ’?PR1706 Receive error’ 
IF C(MSGC1) .NE. 1) 
1 STOP ’?PR1706 Receive length error’ 
IERR=IREADWCMSGC2),STR1,1,0)2 ! Read data 
IF CIERR .LT. 0) STOP ’?PR1706 Read error’ 
IF CICLOSECO) .NE. 0) 
1 STOP ’?PR1706 Close error’ 
CALL PRINTC’In reverse, that becomes: ’) 
CALL PRINTCSTR1) 
CALL EXIT 
END 
CHAPTER 18 


18-1. MACRO-11 

-EDIT/QUTPUT:PR1803.MAC PR1801.MAC 
-TITLE PR1803 SOLUTION TO 18-1 

; This program performs a file-to-file copy by 

; using a dynamically allocated buffer. The 

; program performs only one copy operation. 
-MCALL EXIT -FETCH .LOOKUP .ENTER  .PRINT 


-MCALL .READW .WRITW .CLOSE .SRESET 
»-MCALL .LOCK -UNLOCK .GVAL . SETTOP 
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EMTARG: .BLKW 6 ;EMT argument block 
INFILE: .RADSO /DK TRAN1 XY2Z2/ ;Copy from DK: TRAN1.XYZ 
OUTFIL: .RADSO /DK TRAN2 XYZ/_ ; to DK: TRAN2.XYZ 
LIMITS: .LIMIT ;Program limits 

BUFPTR: .BLKW 1 31/0 buffer address 
ERROR: .BYTE ;Error status byte 


ANNCE: .ASCIZ “Program copies TRAN1.XYZ to TRAN2.XY2Z" 
FCHIMS: .ASCIZ “Error on FETCH of output handler" 
FCH2MS: .ASCIZ “Error on FETCH of input handler" 
LKPMES: .ASCIZ “Error on LOOKUP of input file" 
ENTMES: .ASCIZ “Error on creation of output file” 
RERRMS: .ASCIZ “Read error, copy aborted" 
WERRMS: .ASCIZ "Write error, copy aborted” 
PRTCT: .ASCIZ “Protected output file already exists" 
-EVEN 
-SBTTL SETUP -- Setup Files For Copy 


: This routine sets up files for I/O. 
3 The file specifications are fixed. 


Returns with C-Bit SET on error. 


SETUP: MOV R1,-CSP) ;Save register 
-PRINT #ANNCE ;Announce program 


Allocate buffer from free memory 


ue we we 


-GVAL #266 ;RO = base of USR 
-SETTOP ;SETTOP to base of USR 
-LOCK ;Lock USR in memory 


; Fetch device handlers 


ue 


MOV LIMITS+2,R1 ;Load high limit 


-FETCH R1,#OUTFIL 3Fetch output handler 

BCS FCHIER ;Branch on error 

MOV RO,R1 ;Load new high limit 

-FETCH R1,#INFILE ;Fetch input handler 

BcS FCH2ER ;Branch on error 

MOV RO,BUFPTR ;Save buffer address 
; Open files 


ue 


-LOOKUP #EMTARG, #3, #INFILE 


BCS LKPERR ;Branch on open error 
MOV RO,R1 ;Save file length 
-ENTER #EMTARG, #0, OUTFIL 

Bcc DONE ;Branch on success 


: Error Routines: 


-PRINT #ENTMES sIssue create failure 
BR ERDONE ; message and return 
LKPERR: .PRINT #LKPMES ;Issue open failure 
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BR ERDONE 
FCH2ER: .PRINT #FCH2MS 
BR ERDONE 


FCHiER: .PRINT #FCH1IMS 
ERDONE: .UNLOCK 


; message and return 
sIssue FETCH error 

; message and return 
sIssue FETCH error 
sUnlock USR 


SEC ;Set error flag 
BR DONE 1 
DONE: .« UNLOCK s;Unlock the USR 
DONE1: MOV CSP)+,R1 sRestore R1 
RETURN sReturn to caller 
-SBTTL CPYRTN -- Synchronous Copy 


This routine copies the file opened on channel 
3 to the file opened on channel 0. 
Returns with C-BIT SET on error. 


Note: All registers except RO are preserved. 


CPYRTN: MOV R1,-CSP) ;Save register 
CLR R1 sReset block number 
CLRB ERROR ;Clear error flag 
1$: -READW #EMTARG, #3, BUFPTR, #256. ,R1 
BCC 2$ ‘Branch if read OK 
TSTB #S2 sEnd-Of-File CEOF)? 
BEG EXIT sBranch if so 
BR RDERR ;Issue error message 
2s: -WRITW #EMTARG, #0,BUFPTR, #256. ,R1 
BCS WERR sBranch on write error 
INC R1 ;Update block number 
BR 1$ sAnd read next block 
RDERR: »PRINT #RERRMS sIssue read error 
BR EREXIT ; message and return 
WERR: »-PRINT #WERRMS sIssue write error 
EREXIT: DECB ERROR ;Set error flag 
EXIT: MOV CSP)+,R1 ;Restore register 
TSTB ERROR sError? Cclear C-BIT) 
BEQ 1$ sBranch if not 
SEC 3;Set C-BIT Cerror) 
1$: RETURN s;Return to caller 
-SBTTL CLSCHN -- Close Files 


CLSCHN: .LOCK 


sLock USR 


-CLOSE #3 ;Close input file 
-CLOSE #0 ;Close output file 
BCC RESET ;Branch on success 


»-PRINT #PRTCT 


;Lssue protected file 


PRGCHN: ;Purge files 
RESET: .UNLOCK 3;Unlock USR 
- SRESET ;Reset system 
RETURN ;Return to caller 


»-SBTTL MAIN PROGRAM 
START: CALL SETUP 


;Open files 


BCS 1$ ;Branch on error 
CALL CPYRTN ;Copy the file 
BCS is ;Branch on error 
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CALL CLSCHN sClose the files 
BR 2$ ; and exit 
1$: CALL PRGCHN ;Purge the files 
2$: ~-EXIT sExit 


-END START 


-MACRO PR1803 

-LINK PR1803 

-COPY TT: TRAN1.XYZ 
Files copied: 


“TEST DATA FILE WHICH WILL BE COPIED TO TRAN2.XYZ 


#*#*# EQF ### 
“2TT: to DK: TRAN1.XYZ 


»-RUN PR1803 
Program copies TRAN1.XYZ to TRAN2.XYZ 


- TYPE TRAN2.XYZ 
TEST DATA FILE WHICH WILL BE COPIED TO TRAN2.XYZ 


tte EOF ttt 


18-1. FORTRAN IV 
.EDIT/QUTPUT:PR1804.FOR PR1802.FOR 


PROGRAM PR1804 


Cc 
Cc Solution to 18-1 
Cc 
Cc This program performs a file copy using a 
Cc dynamically allocated buffer. Only one file 
Cc is copied. 
Cc 
Cc HREEE EE CAUTION HHREHRERHEE 
Cc Compile with /NOSWAP option OR use SET USR 
Cc NOSWAP before executing! 
Cc 
LOGICAL*1 SETUP,CPYRTN 
LOGICAL*1 ERROR 
Cc 
10 ERROR = SETUPC) ! Open files 


IF CERROR) GO TO 20 ! Stop on error 
ERROR = CPYRTNC) ! Copy file 
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200 


IF CERROR) GO TO 20 ! Stop on error 
CALL CLSCHN ! Close files 

GO TO 30 

CALL PRGCHN ! Purge channels 
CALL EXIT 

END 


“FUNCTION SETUP 


This routine sets up the files for I/O. 
The file specifications are fixed. 


Function returns .TRUE. on error. 


LOGICAL*1 SETUP 

INTEGER*2 INCHN,OUTCHN 

COMMON /CHNNLS/ INCHN,OUTCHN 
INTEGER*2 INFILEC4),OUTFILC4) 

DATA INFILE/2RDK,3RTRA, 2RN1,3RXYZ/ 
DATA OUTFIL/2RDK,3RTRA, 2RN2,3RXYZ/ 


Annouce the program and allocate channels. 


CALL PRINTC’Program copies TRAN1.XYZ to TRAN2.XYZ‘) 


CALL LOCK ! Lock the USR 
INCHN = IGETCC) ! Allocate input & 
OUTCHN = IGETCC) ! output channels 


Fetch device handlers. 


IF CIFETCHCOUTFILC1)) .NE. 02 GO TO 101 
IF CIFETCHCINFILEC1)) .NE. 02 GO TO 102 


Open input file and create output file. 


LENGTH = LOOKUPCINCHN, INFILE) 

IF CLENGTH .LT. 0) GO TO 103 

IF CIENTERCOUTCHN,OUTFIL,LENGTH) .LT. 0) 
GO TO 104 


CALL UNLOCK ' Unlock USR 
SETUP = .FALSE. § No error 
RETURN 


ERROR ROUTINES 


CALL PRINTC’Error on FETCH of output handler’) 
GO TO 200 

CALL PRINTC’Error on FETCH of input handler’) 
GO TO 200 

CALL PRINTC’Error on LOOKUP of input file’) 

GO TO 200 

CALL PRINTC’Error on creation of output file’) 


CALL UNLOCK ! Unlock USR 
SETUP = .TRUE. ! Error 
RETURN 


END 
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FUNCTION CPYRTN 
Single buffered, synchronous copy routine. 
Function returns .TRUE. on error. 


EXTERNAL IREADW, IWRITW 

LOGICAL*1 CPYRTN 

INTEGER*2 INCHN,QOUTCHN 

COMMON /CHNNLS/ INCHN,OUTCHN 

INTEGER*2 BUFPTR, BLOCK 

BLOCK = 0 § Reset block number 


Allocate buffer dynamically. 


IF CIGETSPC256,256*20,BUFPTR) .LT. 0) 
GO TO 102 


Read/write loop. 


IERR=INDIRCIREADW,0,256,1,BUFPTR,0,BLOCK,0,INCHN) 

IF CIERR .GE. 0) GO TO 30 ! Successful read 

IF CIERR .EQ@. €-1)) GO TO 150 . ! End of File 

GO TO 100 § Error 

IF CINDIRCIWRITW,0,256,1,BUFPTR,0,BLOCK,0,OUTCHN) 
-LT. 02 GO TO 101 

BLOCK = BLOCK+1 ! Update block number 

GO TO 20 


ERROR ROUTINES 


CALL PRINTC’Read error, copy aborted’) 
GO TO 140 

CALL PRINTC’Write error, copy aborted’) 
Go TO 140 ; 

CALL PRINTC’Cannot get buffer space’) 
CPYRTN = .TRUE. 

RETURN 


Successful return. 


CPYRTN = .FALSE. 
RETURN 

END 

SUBROUTINE CLSCHN™ 


Close files. 


INTEGER*2 INCHN,OUTCHN 

COMMON /CHNNLS/ INCHN,OUTCHN 

CALL LOCK _ ! Lock USR 

CALL CLOSECCINCHN) 

IF CICLOSECOUTCHN) .EQ@. 4) CALL PRINT 
C’Protected output file already exists’) 
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CALL UNLOCK ! Unlock USR 
RETURN 
END 
SUBROUTINE PRGCHN 
Cc 
c Purge channels. 
Cc 


INTEGER*2 INCHN,OUTCHN 

COMMON /CHNNLS/ INCHN,OUTCHN 

CALL LOCK ! Lock USR 
CALL PURGECINCHN) 

CALL PURGECOUTCHN) 

CALL UNLOCK $ Unlock USR 
RETURN 

END 


-FORTRAN PR1804.FOR/NOSWAP 


-LINK PR1804,SY:FORLIB 


-RUN PR1804 
Program copies TRAN1.XYZ to TRAN2.XYZ 


~DIFF TRAN1.XYZ TRAN2.XYZ 
?SRCCOM-I-No differences found 


CHAPTER 19 


19-1. MACRO-11 
-EDIT/CREATE PR1902.MAC 
-TITLE PR1902 Solution to 19-1 


Program creates the output file specified by 
the user. 


we we we we 


-MCALL .EXIT -CSIGEN .PRINT .WRITW 
-MCALL .CLOSE .SRESET 


EMTARG: .BLKW 6 ;EMT argument block 
LIMITS: .LIMIT ;Program limits 
SPSAVE: .BLKW 1 ;Saved stack pointer 
DEFTYP: .WORD 0,0,0,0 ;Default file types 
BUFFER: .BLKW 256. sFile 1/0 buffer 
BUFFE = é sEnd of I/O buffer 


PRMPT: .ASCIZ "Specify output filename" 
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CSIERR: .ASCIZ “Error on CSI call" 

WERRMS: .ASCIZ "Write error, output aborted" 

PRTCT: .ASCIZ "Protected output file already exists" 
EVEN 
-SBTTL SETUP -- Create Output File 


; This routine gets a command string using the 
CSI and opens the specified output file. 


Returns with C-Bit SET on error. 


ETUP: MOV SP,SPSAVE ;Save stack pointer 
-PRINT #PRMPT ;Display prompt 
-CSIGEN LIMITS+2,#DEFTYP, #0 
MOV SPSAVE , SP ;Restore stack 
BCC 10$ ;Branch on success 
-PRINT #CSIERR ;Issue error message 
SEC ;Set error flag 
10$: RETURN ;Return to caller 
-SBTTL WRTFIL -- Synchronous Output 
? 
; This routine writes to the output file opened 
H on channel 0. 
? 
3 Returns with C-Bit SET on error. 
; 
; Note: All registers except RO are preserved. 
7 ‘4 x 
WRIFIL: MOV R1,-CSP) ;Save registers 
MOV R2,-CSP) 
MOV R3,-(CSP) 
CLR R3 sClear counter 
CLR R1 sClear block number 
10$: MOV *BUFFER,R2 sLoad buffer address 
20$: MOV R3, CR2)-+ sStore counter 
INC R3 ;Increment counter 
CMP R2, #BUFFE sAt end of buffer? 
BNE 20$ ;Loop if not 
-WRITW #EMTARG,#0,#BUFFER, #256. ,R1 
BCS WERR ;Branch on error 
INC R1 ;Update block number 
CMP R1,#10. 310. blocks written? 
BLT 10$ sBranch if not 
CLC ;Clear error flag 
BR EXIT ;Otherwise, done 
WERR: -PRINT #WERRMS sIssue write error 
SEC ;Set error flag 
EXIT: MOV CSP)+,R3 ;Restore registers 
MOV CSP)+,R2 
MOV CSP)+,R1 
RETURN sReturn to caller 
-SBTTL CLSCHN -- Close File 
CLSCHN: .CLOSE #0 ;Close output file 


BCC RESET ;Branch on success 
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-PRINT #PRTCT ;Issue file protected 
PRGCHN: Purge output file 
RESET: .SRESET ;Reset system 
RETURN ;Return to caller 
-SBTTL MAIN PROGRAM 
START: CALL SETUP ;Open output file 
BCS START ;Loop on error 
CALL WRTFIL ;Write file 
BCS - 10$ ;Branch on error 
CALL CLSCHN ;Close the output 
BR 20$ 3; file and exit 
10$: CALL PRGCHN ;Purge output file 


20$: ~-EXIT : sExit 
»END START 


-EXECUTE PR1902.MAC 
Specify output filename 
*DK: TEST1.DAT= 


-DUMP/TERMINAL TEST1.DAT/NOASCII 

DK: TEST1.DAT 

BLOCK NUMBER 000000 

000/ 000000 000001 000002 000003 000004 000005 000006 000007 
020/ 000010 000011 000012 000013 000014 000015 000016 000017 
040/ 000020 000021 000022 000023 000024 000025 000026 000027 
0607 000030 000031 000032 000033 000034 000035 000036 000037 
100/ 000040 000041 000042 000043 000044 000045 000046 000047 
120/ 000050 000051 000052 000053 000054 000055 000056 000057 
140/ 000060 000061 000062 000063 000064 000065 000066 000067 


760/ 000370 000371 000372 000373 000374 000375 000376 000377 


BLOCK NUMBER 000001 

000/ 000400 000401 000402 000403 000404 00040S 000406 000407 
020/ 000410 000411 000412 000413 000414 000415 000416 000417 
040/ 000420 000421 000422 000423 000424 000425 000426 000427 


-DIR TEST1.DAT 

21-Mar-84 
TEST1 .DAT 10 21-Mar-84 
1 Files, 10 Blocks 

SS2 Free blocks 
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19-1. FORTRAN IV 


-EDIT/CREATE PR1902.FOR 


onoaNgnang 


Qoananan 


PROGRAM PR1902 
Solution to 19-1. 
Program creates a 10 block long output file. 


LOGICAL*1 SETUP,WRTFIL 
LOGICAL*1 ERROR 


ERROR = SETUPC) ! Open output file 
IF CERROR) GO TO. 10 ! Try again on error 
ERROR = WRIFILNC) ! Output the data 

IF CERROR) GO TO 20 ! Stop on error 

CALL CLSCHN ! Close output file 
GO TO 30 

CALL PRGCHN ! Purge output file 
CALL EXIT 

END 


FUNCTION SETUP 


This routine gets a command string and creates 
the specified output file. The CSI is used. 


Returns .TRUE. on error. 


LOGICAL*1 SETUP 

INTEGER*2 OUTCHN 

COMMON /CHNNLS/ OUTCHN 

LOGICAL*1 FRSTTM 

DATA FRSTTM/.TRUE./ 

INTEGER*2 DEFTYPC(4),FILESC39),LENGTH 
DATA DEFTYP/4*0/ 


IF €.NOT. FRSTTM) GO TO 10 
QUTCHN = IGETCC) ! Allocate output 
FRSTTM = .FALSE. ‘! channel only once 


Qutput prompt and parse command string. 


CALL PRINTC’Specify output file:’) 
IF CICSICFILES,DEFTYP,,,0) .NE. 02 GO TO 100 


Fetch device handler and create output file. 


IF CIFETCHCFILESC1)) .NE. 0) GO TO 101 

IF CIENTERCOUTCHN,FILESC1),10) .LT. 0) 
Go TO 104 

SETUP = .FALSE. § No error 

RETURN 
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104 
200 


qonaonanng 


oO 


50 


140 


i?) 


Qa 


ERROR ROUTINES 


CALL PRINTC’Error on CSI call’) 

GO TO 200 

CALL PRINTC’Error on FETCH of output handler’) 
GO TO 200 

CALL PRINTC’Error on creation of output file’) 
SETUP = .TRUE. ! Error 

RETURN 

END 

FUNCTION WRTFIL 


Single buffered, synchronous output routine. 
Returns .TRUE. on error. 

LOGICAL*1 WRTFIL 

INTEGER*2 QUTCHN 

COMMON /CHNNLS/ QUTCHN 

INTEGER*2 BUFFERC2S56) , BLOCK 

Build a buffer and write it to the file. 

ICT = 0 ! Reset counter 


DO SO BLOCK=0,9 
DO 10 I1=1,256 


BUFFERCI) = ICT ' Store counter 
ICT = ICT+1 ! Increment counter 
CONTINUE 


IF CIWRITWC256,BUFFER,BLOCK,QUTCHN) .LT. 0) 
co TO 101 

CONTINUE 

WRTFIL = .FALSE. ! Indicate success 

RETURN 

CALL PRINTC’Write error, output aborted’) 

WRTFIL = .TRUE. 

RETURN 

END 

SUBROUTINE CLSCHN 


Close output file. 


INTEGER*2 OUTCHN 

COMMON /CHNNLS/ OUTCHN 

IF CICLOSECOUTCHN) .EQ@. 4) CALL PRINT 
(’Protected output file already exists’) 

RETURN 

END 

SUBROUTINE PRGCHN 


Purge channel. 


INTEGER*2 OUTCHN 
COMMON /CHNNLS/ QUTCHN 
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CALL PURGECOUTCHN) 
RETURN 
END 


~-EXECUTE/LINKLIB:SY:FORLIB PR1902.FOR 
Specify output filename 
*DK: TEST2.DAT= 


-DUMP/TERMINAL TEST2.DAT/NOASCII 

DK: TEST2.DAT 

BLOCK NUMBER 000000 

000/ 000000 000001 000002 000003 000004 00000S 000006 000007 
020/ 000010 000011 000012 000013 000014 000015 000016 000017 
040/ 000020 000021 000022 000023 000024 000025 000026 000027 
060/ 000030 000031 000032 000033 000034 000035 000036 000037 
1007 000040 000041 000042 000043 000044 000045 000046 000047 
1207 000050 000051 000052 000053 000054 000055 000056 000057 
140/ 000060 000061 000062 000063 000064 000065 000066 000067 


-DIR TEST2.DAT 

21-Mar-84 

TEST2 .DAT 10 21-Mar-84 
1 Files, 10 Blocks 

S02 Free blocks 


CHAPTER 20 


20-1. MACRO-11 
-EDIT/CREATE PR2001.MAC 


-TITLE PR2001 Solution to 20-1 

-ENABL LC 

-MCALL .DATE -PRINT .EXIT ~-THAIT .QSET 
-MCALL .TTINR  .PEEK -POKE «-MRKT »RCTRL 


-GLOBL TIME DATE ;SYSLIB routines 

JSW = 44 ;Job Status Word 

LOWER = 40000 sLower Case bit 

SPEC = 10000 ;Special TT mode bit 

RETRN = 100 sInhibit TT wait bit 
EMTBLK: .BLKW 4 ;EMT Argument block 
TIMARG: .BYTE 1,0 ;TIME argument block 

.- WORD TIMBF 
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DATARG: .BYTE 1,0 ;DATE argument block 
-WORD DATBF 

DELAY: »~WORD 0,2.*60. 32 second delay (tics) 

LIMIT: .WORD 0,20.*60. sTime limit C20 secs) 

FLAG: - WORD 0 320 secs delay expired 

QEL: . BLKW 20.*10. sQueue element buffer 

MSG: -ASCII “The time is: ™ 


TIMBF: .ASCII “HH:MM:SS, on ™ 

DATBF: .ASCIZ “DD-MMM-YY" 

NOTIM: -ASCIZ "Please set the date and time" 
NOQUE: .ASCIZ “Not enough queue elements" 
INSTR: .ASCII “Type as much as you can in 2" 


-ASCIZ "™ seconds, starting now:" 
OUT: -ASCII <¢15><12>"You managed to type:" 
ASCII ¢15><12><12> 
INBF: -BLKB 80. 
~EVEN 
START: .PEEK #EMTBLK, #JSW 3;Get JSW 
MOV RO,R1 ;Copy JSW into R1 
BIS #LOWER,R1 sEnable lower case 
-POKE #EMTBLK,#JSW,R1 ;Set JSW 
-RCTRLO sReset Control/O 
MOV #TIMARG,RS sLoad argument block 
JSR PC,TIME ;CALL TIME 
- DATE sGet date 
TST RO ;Date specified? 
BNE GO1 ;Branch if so 
»-PRINT #NOTIM 3;No, ask for user 
»EXIT ; to set date/time 
GO1: MOV *DATARG,RS ;Load argument block 
JSR PC,DATE ;CALL DATE 
-PRINT #MSG ;Print date and time 
-QSET #QEL,#20. sAllocate queues 
»-MRKT #EMTBLK,#LIMIT,#CRITN, #1 
BCC LOOP sBranch on success 
NO: -PRINT #NOQUE ;Print error message 
EXIT sAnd exit 
LOOP: TST FLAG ;Timer expired? 
BNE STOP ;Branch if so, quit 
«PRINT #INSTR ;Display instructions 
»-PEEK *EMTBLK, #JSW ;Enable special TT 
MOV RO,R1 3; mode and inhibit 
BIS #SPEC!RETRN,R1 3; TT wait 
-POKE *EMTBLK,#JSW,R1 3;Set JSW 
~RCTRLO sReset Control/O 
~-TWAIT #EMTBLK,#DELAY ;Wait for 2 seconds 
BCS NO ;Branch on error 
MOV *INBF,R2 sLoad buffer address 
10$: »TTINR ;Read a character 
BCS 20$ sBranch if none 
MOVB RO, CR2)+ ;Add char to buffer 
BR 10$ ;Read next char 
20$: »-PEEK *EMTBLK, #JSW ;Disable special TT 


MOV RO,R1 ; mode and enable 
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BIC #SPEC!RETRN 3; TT wait 
-POKE #EMTBLK,#JSW,R1 3;Set JSW 
-RCTRLO ;Reset Control/O 
CLRB CR2) 3;Add terminator byte 
-PRINT #QUT ;Display text 
BR LOOP ;And repeat 

STOP: MOV #TIMARG,RS ;Load argument block 
JSR PC,TIME ;CALL TIME 
MOV *#DATARG,RS ;Load argument block 
JSR PC, DATE ;CALL DATE 
«PRINT #MSG ;Display date & time 
~EXIT sAnd exit 


; ** MARK TIME COMPLETION ROUTINE ** 


CRTN: MOV #1,FLAG ;Set time expired 
RTS PC sReturn 
~ END START 

-MACRO PR2001 

»-LINK PR2001,SY:FORLIB 

»-RUN PR2001 


The time is: 14:40:02, on 20-MAR-84 
Type as much as you can in 2 seconds, starting now: 


You managed to type: 


thi 
Type as much as you can in 2 seconds, starting now: 


You managed to type: 


sabed 
Type as muech as you can in 2 seconds, starting now: 


You maanaged to type: 


ef aaaaaaaaAaAaAAAAAAAAAAA 
Type asa much as you can in 2 seconds, starting now: 


You managed to type: 


aaaaaaaaaaaaaa | jj 
Type as much as you can in 2 seconds, starting now: 


You managed to type: 


Jj 


Type as much as you can in 2 seconds, starting now: 


You managed to type: 
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Type as much as you can in 2 seconds, starting now: 
You managed to type: 


121 
Type as much as you can in 2 seconds, starting now: 


You managed to type: 


21212121212121212121212 
The time is: 14:40:23, on 20-MAR-84 


20-1. FORTRAN IV 
-EDIT/CREATE PR2001.FOR 


PROGRAM PR2001 


Cc 
Cc Solution to 20-1. 
Cc “ 
Cc Get and print time and date, exiting if no date. 
Cc Loop reading from the terminal every 2 seconds 
Cc for a total of 20 seconds. Print the new time 
Cc and date and exit. 
C 
EXTERNAL CRTN 
BYTE MSGBFRC 100), TIMSTRC8), TODAYCS) 
INTEGER*2 AREAC4), DELAYC2), FLAG 
COMMON /DATA/ FLAG 
C 
CALL IPOKEC"44, IPEEKC'"44).0R.%40000) 
CALL RCTRLO ! Enable lower case 
CALL TIMECTIMSTR) ! Get current time 
CALL DATECTODAY) ! and date 
IF CTODAYC1) .EQ@. % “%) 
1 STOP ‘Please set the date and time’ 
TYPE 10,TIMSTR, TODAY 
10 FORMAT (€’ The time is: ’,8A1,’%, on ’,9A1) 
IF CIQSETC3) .NE. 0) 
1 STOP ‘Not enough queue elements’ 
FLAG = 0, ! Clear timer flag 
IERR = ITIMERCO,0,20,0,AREA,1,CRTN)D 
DELAYC1) = 0 ! Build time delay 
DELAYC2) = 2*60 ! (delay 2 secs) 
20 IF (FLAG .NE. 02 GO TO 60 ! Timer expired 


TYPE 25 
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25 FORMAT C’ Type as much as you can in 2’, 
1 ‘seconds, starting now:’/) 
CALL POKEC'"44, IPEEKC"44).0R.%10100) 
CALL RCTRLO ! Change JSW bits 
IERR = ITWAITCDELAY) §! Wait for 2 seconds 
DO 40 I[=1,100 
IERR = ITTINRC) ! Accept a character 
IF CIERR .LT. 0) GO TO SO ! None available 
MSGBFRCI) = IERR § Store character 
40 CONTINUE 
50 MSGBFRCI) = 0 § Mark end of buffer 
CALL IPOKEC'44, IPEEKC"44).AND..NOT."10100) 
CALL RCTRLO !' Reset JSW bits 
TYPE SS 
SS FORMAT €’ You managed to type:’,/) 
CALL PRINTCMSGBFR) ! Display text read 
GO TO 20 ! Repeat until timeout 
60 CALL TIMECTIMSTR) § Get current time 
CALL DATECTODAY) ! and date 
TYPE 10,TIMSTR, TODAY ! Output time & date 
CALL EXIT ! Exit 
END 


SUBROUTINE CRTNCID) 
** TIMER COMPLETION ROUTINE ** 
Runs after 20 seconds and sets a flag in the 


common data region to indicate that the MAIN 
PROGRAM should now stop. 


qQngaoaoaonan 


INTEGER*2 ID,FLAG 

COMMON /DATA/ FLAG 

FLAG = 1 ! Set timer flag 
RETURN 

END 


-EXECUTE/LINKLIBRARY:SY:FORLIB/FORTRAN PR2001 
The time is: 15:02:49, on 20-MAR-84 
Type as much as you can in 2 seconds, starting now: 


You managed to type: 
abc 


Type as much as you can in 2 seconds, starting now: 


You managed to type: 
dthis is a test 


Type as much as you can ‘in 2 seconds, starting now: 


You managed to type: 
of the emerg 
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Type as much as you can in 2 seconds, starting 


You managed to type: 
ency 


Type as much as you can in 2 seconds, starting 


You managed to type: 
121212 © 


Type as much as you can in 2 seconds, starting 


You managed to type: 
129999999 


Type as much as you can in 2 seconds, starting 


You managed to type: 
9999999999999999999999999999999999999999 


Type as much as you can in 2 seconds, starting 


You managed to type: 
9999999999 


The time is: 15:03:11, on 20-MAR-84 


now: 


now: 


now: 


now: 


now: 


Index 


ABORT command, 95 
Absolute locations: 
reaching from FORTRAN IV pro- 
grams, 27-30 
reaching from MACRO-11 pro- 
grams, 25-27 
ACCEPT statement, 43, 66 
AJFLT function, 13 
AND operator, 29 
Arguments: 
for MACRO-11 programmed re- 
quests, 7, 9 
passing of, 9-10 
ASCII directive, 79 
ASCIZ directive, 79 
ASECT directive, 22, 45 
Asynchronous mode, 59, 61, 133- 
134 
Asynchronous requests, 135-159 
formats for, 135-136 
for multiple buffering, 136-159 
send and receive, 191 
Asynchronous terminal status, 101 
Asynchronous terminal status word, 
99, 101 


Background jobs, starting, 39-40 

See also Foreground/Background 
monitor 

BIC instruction, 27, 77 

BICB instruction, 27 

BIS instruction, 27, 77 

BISB instruction, 27 

BLKB directive, 79 


Blocking, 176, 177-181 
overriding, 76-79 
programmed requests and, 178 
RMON and, 177-181 

Block replaceable devices, transfers 

to, 120-121 

BUFFER option, 38, 211 

Buffers, 60 
send and receive, 194-196 
shared, 197-201 
terminal I/O, 70-72, 79-82 
See also Multiple buffering 

BYTE, 73, 79 

Byte 52, 11, 12, 22 

Byte 53, 11, 23, 28 

Byte 56, 23 

Byte 57, 23 

Byte 276, 31 

Byte 277, 31 

Bytes, accessing, 26-27 


CALL statement, 13, 198 
CDFN request, 124, 220 
Chain information area, 43 
Chaining, 43-46 
in FORTRAN IV programs, 46 
in MACRO-11 programs, 44-46 
CHAIN request, 45, 46 
Channel: 
closing, 121-122 
opening, 115-117 
selecting, 114 
system-maintained, 123-124 
Channel copy request, 203 
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Index 


Channel numbers, 114 
Channel status word (CSW), 169 
CHCOPY request, 203 
Clock. See Time 
CLOSEC request, 65, 114, 122 
CLOSE request, 65, 116, 121-122, 
170, 203 
CLOSE statement, 170, 220 
CMKT request, 263-264, 269 
CNTXSW request, 182, 183 
Commands, passing, 42-43 
Command string: 
format of, 228-230 
information in, 228 
Command String Interpreter (CSI), 
65, 220, 227-247 
calling in general mode, 233-237 
calling in special mode, 237-247 
file number assignment by, 232, 
233 
modes, 233-247 
operations performed by, 228 
options, 230, 235-237, 239, 240 
program interface with, 231-233 
COMMON block, 46 
Communication, 190-206 
through files, 201-203 
through send and receive requests, 
190-196 
through shared buffers, 197-201 
Completion routines, 161-171 
conventions for writing, 168-169 
restrictions on, 169-171 
scheduling under FB monitor, 
165-168 
scheduling under SJ monitor, 163- 
164 
COMPLEX, 49 
CONCAT subroutine, 85 
Configuration word, 31 
Console, system, 94-96 
Context switching, 176, 181-182 
Conversion routines, 48, 51-52 
CSI. See Command String Interpreter 
CSIGEN request, 65, 233-235 
CSISPC request, 65, 238 
CSTRING argument, 231 
CSW. See Channel status word 
CTRL/C, 88, 95 
CTRL/F, 95 
CTRL/O, 88-89, 100 
CTRL/X, 95 
C.USED, 124 
CVTTIM routine, 253, 259 


Data block, 123-124 
DATA statement, 79 
Data structures, 122-127 
system-maintained channels, 123- 
124 
system-maintained I/O queue ele- 
ments, 125-127 
user-created file specifications, 
123 
Data transfer, 189-206 
communication through files, 201- 
203 
communication through send and 
receive requests, 190-196 
communication through shared 
buffers, 197-201 
coordinated foreground/ 
background systems, 203-205 
Date (system), 250-258 
accessing, 255-257 
maintaining, 254-255 
setting, 257-258 
writing programs independent of 
line frequency, 257 
DATE monitor command, 255, 257, 
258 
DATE request, 31, 255-256, 257, 259 
DEFTYP argument, 231, 232 
DEFTYP block, 232 
Device handlers, 63-64, 127-129, 202 
fetching, 106, 107, 113, 235 
releasing, 122 
DL11 interface, 94, 95 
Double-buffered copy. See Multiple 
buffering 
DOUBLE PRECISION, 49 
DSTATUS request, 122, 127-129, 
220 
DZ11 interface, 94, 95 


ELINIT, 183, 204 
EMT (emulator trap) instruction: 
execution of, 5-7 
generation of, 9-10 
ENTER request, 65, 115-117, 121, 
124, 202-203, 220, 223, 235 
ERRLOG, 183, 204 
Error checking code, 11 
Error conditions, 14-16 
control of, 15 
floating point exception handlers, 
16 
in FORTRAN IV requests, 14 


Index 


in MACRO-11 requests, 10-12 
serious, 12, 15 
trap handlers, 15-16 
Error handling: 
under the FB monitor, 76, 78 
under the SJ monitor, 74-75, 78 
techniques for, 78 
under the XM monitor, 78 
Error logging, 204 
Error return: 
in FORTRAN IV programmed 
requests, 14 © 
in MACRO-11 programmed 
requests, 10-12 
ERROUT, 183, 204 
Event-driven I/O requests, 159-172 
applications for, 171-172 
completion routines, 161-171 
under FB monitor, 165-168 
priority levels, 162 
scheduling, 162-168 
send and receive, 191 
under SJ monitor, 163-164 
Event-driven mode, 59-60, 134 
Exiting, 40-42 
from FORTRAN IV programs, 41- 
42 
from MACRO-11 programs, 41 
EXIT request, 41, 42 
Extended Memory (XM) monitor: 
chaining with, 44 
error handling under, 78 
impure area of, 32-34 
mark-time routines under, 259 
program high limit in, 22 
queue elements under, 125 
SETTOP request under, 215-217 
system device handler under, 63 
system message handler under, 
191 
USR swapping and, 219 
Extension configuration word, 31 


EXTERNAL statement, 161, 169, 262 


FB monitor. See Foreground/ 
background monitor 

FETCH request, 65, 107, 113, 220, 
223 


FIFO. See First in—first out method, 


169 
File input/output, 64-65 


Files, communication through, 201- 


203 
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File specification format, 44, 46 
See also RADSO file descriptors 
File specifications, 123, 242 
Fill character, 23 
Fill count, 23 
First in—first out (FIFO) method, 
165, 166, 184, 194, 202 
Floating point exception handlers, 
16 
Foreground/Background (FB) 
monitor: 
error handling under, 76, 78 
impure area of, 32-34 
information areas in, 21 
mark-time routines under, 259 
memory allocation under, 210 
overriding job blocking under, 76- 
79 
priority levels under, 125 
queue elements under, 125 
scheduling under, 165-168, 176- 
186 
system device handler under, 63 
system message handler under, 
191 
time under, 250 
Foreground/background systems, co- 
ordinated, 203-205 
Foreground jobs: 
PRINT request from, 85 
starting, 38 
FORTRAN IV completion routines, 
164, 169, 170-171 
FORTRAN IV OTS, 42, 43, 66-67, 
114, 170, 213-214, 221 
FORTRAN IV programmed requests, 
12-14 
asynchronous //O, 135-136 
closing a channel, 121-122 
Command String Interpreter and, 
231, 232, 238 
date, 256-257, 258, 259 
device status, 128 
disabling CTRL/C, 88 
dynamic allocation of memory, 
213-214 
error return, 14 
event-driven, 161 
fetching device handlers, 107, 113 
for file I/O, 65 
form of, 13 
GTLIN request, 86 
IGETSP request, 218 
line-oriented input, 86 


Index 


FORTRAN IV requests (continued ) 
mark-time requests, 261-262, 264 
multiterminal, 96 
opening a channel, 117 
PRINT request, 85 
for processing ASCII strings in CSI 
format, 65 

queued J/O, 63, 107, 110-112, 117, 
121-122, 126-127 

resetting CTRL/C, 88 

resetting CTRL/O, 89 

resuming a job, 185 

send and receive, 191 

special function I/O, 66 

suspending a job, 185 

synchronous I/O requests, 118 

system-maintained channels, 124 

system-maintained queue ele- 
ments, 126-127 

terminal I/O, 61, 73-74 

time, 251, 252, 258, 259 

timed waits, 266-267, 269 

See also names of specific re- 
quests 

FORTRAN IV programs: 
buffers, 79, 81 
chaining in, 46 
CSI special mode in, 241, 245-247 
error handling, 75, 76, 78 
exiting from, 41-42 
1/O statements in, 62 
for multiple buffering, 145-147, 

156-159 
overriding job blocking in, 77 
passing commands from, 42-43 
RAD50 in, 49 


reaching absolute locations from, , 


27-30 
REENTER command in, 39 
retrieving data from impure area, 
34 - 
retrieving data from RMON fixed 
offset area, 32 
shared buffers in, 197-198 
suspending execution of, 266-267, 
269 
FORTRAN IV subroutines, 7, 8 
See also FORTRAN IV pro- 
grammed requests; System 
services 
- FRUN command, 38, 211 
FRUN/TERMINAL, 96 


General mode (CSI), 233-237 
functions, 234 


in MACRO-11 program, 241, 243- 

244 

GET command, 39 

GTIM request, 31, 251, 255, 256, 259 

GTJB (get job information) request, 
33, 211 

GTLIN request, 7, 61, 86-88, 220, 
231 

GVAL request, 32, 97, 217 


HERR, 15 


IADDR routine, 197 
I.BLOK, 178-180 
ICDFN request, 124 
ICHCPY request, 203 
ICMKT request, 264, 269 
ICSI request, 65, 238-241 
IDATE request, 256-257, 259 
IDSTAT request, 128 
IENTER request, 65 
IFETCH request, 65, 107, 113 
IFREEC request, 65, 114, 170 
IGETC request, 65, 114, 170 
IGETSP request, 214, 217-219 
Impure area, 32-34 
contents of, 32-33 
locations of, 33 
retrieving data from, 33-34 
INDIR subroutine, 197-198, 218 
Inhibit wait bit, 97 
Input/output (I/O) modes, 56-61, 
133-134 
asynchronous, 59, 61, 133-134, 
135-159 
event-driven, 59-60, 134, 159-172 
nonsynchronous, 57-58, 59-60 
selection of, 60-61 
synchronous, 56-57, 58, 60 
Input/output requests: 
asynchronous, 135-159 
blocking and, 178 
event-driven, 159-172 
synchronous, 117-120 
Input/output systems, 55-67 
file I/O, 64-65 
FORTRAN IV OTS I/O, 66-67 
multiterminal, 93-102 
nonsynchronous queued, 131-173 
queued I/O, 63-64, 105-173 
special function I/O, 66 
terminal I/O, 61-63, 69-90 
INTEGER, 73, 169, 218, 232 
INTEGER#2, 49, 198, 257, 267 
INTEGER+#4, 8, 13, 253 


Index 


Interfaces, 94, 95 

I/O. See Input/output 

IPEEKB function, 28, 218 

IPEEK function, 27-30, 197, 218 

IPOKEB function, 28, 218 

IPOKE function, 27-30, 197, 218 

IPUT function, 32 

IQSET request, 126, 135, 260, 266 

-TRAD50 function, 52 

IREADC request, 63, 161, 169 

IREADF request, 63, 161, 169 

IREAD request, 63, 65, 135 

IREADW request, 63, 118, 218 

ISCHED request, 262, 269 

ISDTTM request, 255, 258, 259 

ISLEEP request, 267, 269 

ISPFNC request, 66 

ISPFNF request, 66 

ISPFN request, 66 

ISPFNW request, 66 

ISPY request, 32 

LSTATE, 181 

ITIMER request, 262, 269 

ITTINR request, 61, 73-74, 75, 76, 78 

ITTOUR request, 61, 73-74, 75, 76, 
78, 85 

ITWAIT request, 267, 269 

IUNTIL request, 267, 269 

IWAIT request, 135-136 

IWRITC request, 63, 161, 169 

IWRITE request, 63, 65, 135 

IWRITF request, 63, 161, 169 

IWRITW request, 63, 118 


JADD function, 14 

JJCVT function, 253-254 

Job blocking. See Blocking 

Job status word (JSW), 22, 23-24, 26, 
27, 28, 30, 42, 45, 77, 78, 82, 87, 
98, 100, 114 

JSW. See Job status word 

JTIME routine, 253, 259 


KMON, 23, 37, 38, 42-43 


Last in—first out (LIFO) method, 163 
LIMIT directive, 113, 214, 216 
Limits, 22, 25, 113, 211, 214 

See also Memory 
Line-oriented input, 86-87 
Line-oriented output, 84-85 
LINK command, 210 
LINK/XM option, 216 
LIST MEB directive, 10, 11 
Load image code, 5 
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LOCK request, 222, 223, 224 

LOGICAL, 73 

LOGICAL*#1, 79 

Logical unit number (LUN), 97 

LOOKUP request, 12, 65, 115-117, 
121, 124, 202, 204, 220, 223, 
235 

Lowercase bit, 98 

LUN. See Logical unit number 


MACRO-11 completion routines, 
164, 168-169, 170 
MACRO-11 programmed requests, 
7-12 
asynchronous I/O, 135-136 
closing a channel, 121-122 
Command String Interpreter and, 
231, 232, 238 - 
context switching, 182 
date, 255-256, 258, 259 
_ device status, 128 
disabling CTRL/C, 88 
dynamic allocation of memory, 
213 
error return, 10-12 
event-driven, 159-161 
expansion of, 10, 11 
fetching device handlers, 107, 113 
file I/O, 65 
form of, 7-9 
line-oriented input, 86 
mark-time requests, 260-261, 263- 
264 
multiterminal, 96 
opening a channel, 116-117 
passing of arguments, 9-10 
PRINT request, 84, 85 
for processing ASCII strings in CSI 
format, 65 
queued I/O, 63, 107, 108-109, 116- 
117, 121-122, 125-126 
releasing a device handler, 122 
resetting CTRL/C, 88 | 
resetting CTRL/O, 89 
resuming a job, 185 
return of auxiliary information, 12 
send and receive, 191 
serious error conditions, 12 
special function I/O, 66 
suspending a job, 185 
synchronous I/O requests, 118 
system-maintained channels, 124 
system-maintained queue ele- 
ments, 125-126 
terminal I/O, 61, 72-73 
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MACRO-11 requests (continued ) 
time, 251, 258, 259 
timed waits, 266, 269 
See also names of specific re- 
quests 
MACRO-—11 programs: 
buffers, 79, 80 
chaining in, 44-46 
CSI general mode in, 241, 243-244 
error handling, 75, 76, 78 
existing from, 41 
for multiple buffering, 142-144, 
152-155 
overriding job blocking in, 77 
passing commands from, 42 
RAD50 in, 48-49 
reaching absolute locations from, 
25-27 
REENTER command in, 39 
retrieving data from impure area, 
34 ; 
shared buffers in, 197-199 
suspending execution of, 266, 269 
Mark-time routines, 258-269 
cancelling, 263-264 
periodic scheduling, 265 
requests, 269 
scheduling, 260-263 
timed waits, 266, 269 
watchdog routines, 265 
Mask, 28-29 
MCALL directive, 7 
Memory, 209-225 
dynamic allocation of, 211-214 
limits, 22, 25, 113, 211, 214 
SETTOP request and, 214-219 
standard use of, 210-211 
USR control and, 219-224 
MFPS request, 35 
Monitor error byte, 22 
Monitor release number, 31 
Monitor version number 
MRKT request, 205, 260-261, 262, 
269 
MTATCH request, 96, 97, 99, 101 
MTDTCH request, 96, 97, 99, 100 
MTGET request, 96, 97, 99, 100, 101 
MTIN request, 96, 100 
MTOUT request, 96, 100 
MTPRNT request, 96, 100 
MTPS request, 35 
MTRCTO request, 96, 100 
MTSET request, 96, 97, 100 
MTSTAT request, 96, 97 
Multiple buffering, 136-159 


benefits of, 137-141 
flowcharts for, 141, 151, 160 
FORTRAN IV programs for, 145- 
147, 156-159 
implementing, 136 
MACRO-11 programs for, 142- 
144, 152-155 
rules for, 148 
use with computation, 141-159 
Multiterminal programmed requests, 
96 
Multiterminal programming, 96-101 
asynchronous terminal status, 101 
debugging, 100 
sequence for, 98-100 
terminal control blocks, 97-98 
Multiterminal support, 94-96 
hardware configuration, 94 
system console, 94-96 
MWAIT request, 190-191, 201 


NAME option, 38 
Nonsynchronous modes, 57-58, 59- 
60, 133-134 
Nonsynchronous queued in- 
put/output, 131-173 
asynchronous requests, 135-159 
event-driven requests, 159-172 
1/O queue elements, 134-135 
NOSWAP option, 219, 221 
Null byte, 42, 79, 85, 86 


Object time system (OTS), 42, 43, 
66-67, 114, 170, 213-214, 221 

OPEN statement, 170 

Options (CSI), 230, 235-237, 239, 
240 

OR operator, 28, 29 

OTS. See Object time system 


Passwords, 25 
PAUSE option, 38 
PC. See Program counter 
PEEK requests, 9, 25-27, 44, 45 
Periodic scheduling, 265 
POKE requests, 9, 25-27, 44 
PRINT request, 4-5, 7, 9, 61, 84-85 
PRINT statement, 66 
Priorities, 162, 167, 176, 177 
Processor status word (PSW): 
EMT instruction execution and, 
5,6 
gaining access to, 34-35 
Program counter (PC), 5, 6 
Program execution, 37-53 
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chaining, 43-46 

exiting, 40-42 

passing commands to KMON, 42- 

43 

RAD50 file descriptors, 47-52 

starting, 38-40 
Programmed requests, 4-7 

EMT instruction, 5-7, 9-10 

executing, 4-5 

load image code, 5 

synchronous I/O, 110, 118 
PSW. See Processor status word 
PURGE request, 65, 121-122 
PVAL request, 32 


QSET request, 125, 135, 191, 220, 
223, 260, 266 
QUEMAN, 185, 205 
QUEUE, 183, 185, 204-205 
Queued input/output, 63-64, 105-129 
closing a channel, 121-122 
communication requests and, 190 
concepts of, 106-107 
data structures, 122-127 
device handlers, 106, 107, 113, 
122, 127-129 
fetching device handlers, 107, 113 
opening a channel, 115-117 | 
performing, 107-122 
releasing a device handler, 122 
selecting a channel, 114 
standard sequence of requests, 
107, 108-112 
synchronous I/O requests, 117-120 
system-maintained channels, 123- 
124 
system-maintained I/O queue ele- 
ments, 125-127 
transfers to block replaceable de- 
vices, 120-121 
transfers to sequential devices, 
121 
user-created file specifications, 
123 
See also Nonsynchronous queued 
input/output 
Queue element, 106 
in nonsynchronous I/O, 134-135 
structure of, 126 
system-maintained, 125-127 
Queue manager, 165-167 
Queuing system, 204-205 


RAD50 file descriptors, 47-52 
in FORTRAN IV programs, 49 
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in MACRO-11 programs, 48-49 
SYSLIB routines for conversion, 
51-52 
Radix-50 conversion, 8 
RCHAIN subroutine, 46 
R command, 38, 39 
RCTRLO request, 89 
RCVDC request, 204, 205 
RCVDW request, 204 
READC request, 63, 159, 205 
READ request, 63, 65, 135, 138-139, 
148, 149-150 
READ statement, 43, 66 
READW request, 63, 118, 139, 149 
REAL#4, 13, 252 
REAL#8, 49 
Receive buffers, 194-196 
REENTER command, 39 
RELEAS request, 65, 122 
RENAME request, 220 
RESET operation, 41 
Resident Monitor (RMON), 20-34 
blocking and, 177-181 
completion routines and, 165, 168 
fixed offset area of, 30-32 
impure area of, 32-34 
memory allocation and, 211 
memory areas of, 20, 21 
in queued I/O, 106, 120-121, 125 
queue elements and, 125 
SETTOP request and, 216-217 
system code in, 63-64 
system communication area of, 20- 
25 
terminal system codes in, 61 
in transfers to block replaceable 
devices, 120-121 
WAIT request and, 133 
RESUME request, 185 
R format specifier, 48, 49 
RMON. See Resident Monitor 
RMON fixed offset area, 30-32 
application example, 31 
contents of, 30-31 
retrieving data from, 31-32 
RSUM request, 178, 185 
RTI (return from interrupt) instruc- 
tion, 6 
RUN command, 38, 39 
Runnable level, 177 


SCCA request, 88 

Scheduler, 165-167, 181 

Scheduling, 162-168, 175-186 
basic concepts of, 176 
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Scheduling (continued ) 
blocking and, 176, 177-181 
context switching, 176, 181-182 
efficiency in, 182-184 
under FB monitor, 165-168, 182- 
184 
priorities and, 162, 176, 177 
under SJ monitor, 163-164 
waiting for specific events, 184- 
186 
Scheduling pass, 168, 180, 181 
-SDTTM request, 255, 258, 259 
SECNDS function, 251-252, 259 
Send and receive buffers, 194-196 
Send and receive requests, 190-196 
Sequential devices, transfers to, 121 
SERR, 15 
SETCMD request, 42-43, 258 
SET TERM CONSOL, 96 
SETTOP request, 22, 213-219 
IGETSP routine, 217-219 
restrictions on use of, 217 
USR swapping and, 220, 221, 222, 
223 
under XM monitor, 215-217 
SET TT NOQUIET, 88 
SET TT QUIET, 88 
SFPA, 16 
Shared buffers, 197-201 
‘benefits of, 199-200 
disadvantages of, 200 
restrictions on use of, 200 
setting up, 197 
synchronizing access to, 200-201 
Single-character input/output, 72-79 
error handling, 74-76, 78 
FORTRAN IV requests, 73-74 
MACRO-11 requests, 72-73 
overriding job blocking, 76-79 
Single Job (SJ) monitor: 
error handling under, 74-75, 78 
GTJB request, 33 
implementing a waiting. condition 
under, 185 
mark-time routines under, 259 
priority levels under, 162, 170 
queue elements under, 125 
scheduling completion routines 
under, 163-164 
system device handler under, 63 
time under, 250 
SJ monitor. See Single Job monitor 
Special function input/output re- 
quests, 66 
Special mode (CSI), 237-247 


file specifications returned by, 242 
in FORTRAN IV program, 241, 
245-247 
functions, 234 
Special mode terminal bit, 25, 98 
SPFUN request, 66 
SPND request, 178, 185, 204 
SRESET request, 122 
SRUN/TERMINAL, 96 
STACK option, 22, 210 
Stack pointer, 22 
START command, 39-40 
STOP command, 41 
Subroutines. See System services 
SUSPND request, 185 
Synchronous input/output requests, 
117-120, 178, 191 
Synchronous mode, 56-57, 58, 60 
SYSCOM. See System communica- 
tion area 
SYSLIB, 3, 7, 13, 41 
SYSLIB conversion routines, 51-52 
SYSMAC.SML, 7 
System communication area (SYS- 
COM), 20-30 
application examples, 24-25 
contents of locations in, 22-23, 24 
gaining access to, 25-30 
job status word, 22, 23-24 
System console, 94-96 
System generation features word, 31 | 
System information, 19-35 
gaining access to, 25-30 
impure area, 32-34 
processor status word, 34-35 
RMON fixed offset area, 30-32 
system communication area, 20-25 
System job option, 176 
System macros. See MACRO-11 
programmed requests 
System-maintained channels, 123- 
124 
System-maintained queue elements, 
125-127 
System message handler, 191-194 
System services, 3-16 
error conditions in requests, 10- 
12, 14-16 
FORTRAN IV programmed re- 
quests for, 12-14 
MACRO-11 programmed requests 
for, 7-12 
programmed requests for, 4-7 
trap handlers, 15-16 
types of, 7, 8 
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System time and date. See Date; 
Time 


Terminal configuration word, 97, 98, 
99 
Terminal control blocks (TCBs), 97- 
98 
Terminal echo, 83 
Terminal input/output, 61-63, 69-90 
buffers, 70-72, 79-82 
error handling, 74-76, 78 
error processing schemes, 78 
handling CTRL/C, 88 
handling CTRL/O, 88-89 
input from indirect command 
files, 87-88 
line-oriented input, 86-87 
line-oriented output, 84-85 
single-character I/O, 72-79 
special characters, 71-72 
TERMINAL option, 94 
Terminals, multiple. See Multiter- 
minal programming; Multiter- 
minal suport 
Terminal special mode, 83-84 
Terminal state byte, 99 
TIMASC routine, 253, 259 
Time (system), 31, 250-258 
accessing, 251-253 
converting to 32-bit integers, 253- 
254 
maintaining, 250-251 
setting, 257-258 
writing programs independent of 
line frequency, 257 
Time-dependent programs, 249-269 
mark-time routines, 258-269 
system time and date, 250-258 
Timed waits, 266-267, 269 
TIME monitor command, 250, 257, 
258 
TIME request, 252, 259 
TLOCK request, 223-224 
TOP option, 211 
TRANSFER option, 38 
Trap handlers, 15-16 
TRPSET programmed request, 16 
TTINR request, 61, 72-73, 75, 76, 78, 


83 
TTOUTR request, 61, 72-73, 75, 76, 
78 
TTYIN request, 61, 73, 75, 76, 78, 
83, 87 
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TTYOUT request, 61, 73, 75, 76, 78, 
85 

TWAIT request, 178, 184, 186, 266, 
269 

TYPE statement, 66 


UNLOCK request, 222, 223 . 
User-created file specifications, 123 
User error byte, 23, 28 
User Service. Routine (USR) load ad- 
dress, 23 
USR, 65, 106, 115, 116, 170 
USR base address, 31 
USR contention, 223-224 
USR operations, sequential, 222-223 
USR requests, 178 
USR swapping, 170, 215, 219-224 
algorithm, 219-221 
problems and restrictions on, 221- 
222 


Virtual debugging technique (VDT), 
100 
V overlays, 216 


WAIT request, 59, 61, 133, 135-136, 
139, 148, 149-150, 178, 184 

Waits, timed, 266-267, 269 
Watchdog routines, 265 
Word, 5, of GTJB array, 33 
Word 40, 22, 38 
Word 42, 22 
Word 44, 22, 23-24, 26, 45 

See also Job status word 
Word 46, 23, 28, 220 
Word 50, 22, 25 
Word 54, 22, 26, 27-28 
Word 56, 182 
Word 266, 31 
Word 300, 31 
Word 370, 31 
Word 372, 31 
Word locations, accessing, 26 
WRITC request, 63, 159, 205 
WRITE request, 63, 65, 135, 138-139 
WRITE statement, 66, 150 
WRITW request, 63, 118 


XM monitor. See Extended Memory 
monitor 


Zero byte, 43 


Programming with RT-11, Volume 2 teaches programmers to incorporate the 
RT-11 system services into the MACRO-11 or FORTRAN IV programs they 
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